Home Assistant GSM SMS Add-on Development

Development instructions for working with the ha-legacy-gsm-sms repository, which provides legacy GSM SMS notifications via GSM modem using HACS or HA Add-on options.

Critical Rules

1. NEVER Copy Entire Files Between Add-ons

This repository contains multiple add-on variants with **intentional differences**:

**ALWAYS make surgical, line-by-line edits when syncing features or fixes between add-ons to preserve custom settings.**

**NEVER copy entire files from one add-on to another.**

2. Test Add-on Custom Settings (addon-test-current/)

The test add-on has these **intentional differences** that must be preserved:

#### config.yaml

#### support.py

3. Before Editing Any Config File

1. **Read the file first** using available file reading tools

2. **Identify what needs to change** - only those specific lines

3. **Make surgical edits** - change only what's necessary

4. **Verify with diff** - check that only intended changes were made

4. Tuning Values - Do NOT Change

These values have been tuned for this project and differ from upstream:

5. Syncing Features Between Add-ons

When adding a new feature to both production and test add-ons:

1. Implement in production add-on first (`addon-gsm-gateway/`)

2. For Python files (`mqtt_publisher.py`, `run.py`): These CAN be synced (except `support.py`)

3. For `config.yaml`: Make **individual line edits** - never copy the whole file

4. Always verify test add-on customizations are preserved after changes

6. Version Bumping

Both should be bumped together when features are added.

7. Feature Implementation Checklist

When adding a new SMS feature, it must be implemented in ALL these places:

**Don't mark as complete until all four are done.**

8. Phone Number Validation

Phone numbers can contain: `+`, digits, spaces, `-`, `(`, `)`, `,`

The `+` character can appear **anywhere** (not just at the start) because multiple international numbers are comma-separated: `+1234567890,+0987654321`

**Correct regex:** `^[\+\d\s\-\(\),]*$`

**Wrong regex:** `^\+?[\d\s\-\(\),]*$` (only allows + at start)

9. Validation Before Completion

Before marking a task as complete:

1. Run Python syntax check on all modified `.py` files

2. Test the logic with edge cases (multiple values, empty values, special characters)

3. Verify with diff tools that only intended changes were made

4. Check that both production AND test add-ons are updated (if applicable)

5. Confirm documentation matches the implementation

10. When in Doubt, Ask

If unsure whether a file has custom settings or special handling:

Upstream Reference

This project is based on [PavelVe/hassio-addons](https://github.com/PavelVe/hassio-addons). When syncing upstream features, always credit the source in CHANGELOG.md.

Constraints