ha-legacy-gsm-sms Addon Development

Development guidelines for maintaining the ha-legacy-gsm-sms Home Assistant addon, which provides legacy GSM SMS notifications via GSM-modem using HACS or HA Add-on options.

Critical Development Rules

File Synchronization Between Addon Variants

This repository contains multiple addon variants with intentional differences:

**NEVER copy entire files between addons.** Always make surgical, line-by-line edits to preserve custom settings.

Test Addon Custom Settings (addon-test-current/)

The test addon has intentional differences that MUST be preserved:

**config.yaml customizations:**

**support.py customizations:**

File Editing Protocol

Before editing any configuration file:

1. Read the file first using appropriate tools

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

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

4. Verify with diff that only intended changes were made

Tuned Values (Do NOT Change)

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

Feature Implementation Workflow

When adding a new feature to both production and test addons:

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

2. Python files (`mqtt_publisher.py`, `run.py`) CAN be synced between addons (except `support.py`)

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

4. Always verify test addon customizations are preserved after changes

Version Bumping Convention

Both versions should be bumped together when features are added.

SMS Feature Implementation Checklist

When adding a new SMS feature, implement in ALL these locations:

1. `mqtt_publisher.py` - MQTT command handling

2. `run.py` - REST API endpoint

3. `README.md` - Documentation

4. `CHANGELOG.md` - Release notes

Do not mark task complete until all four are implemented.

Phone Number Validation Rules

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

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

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

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

Pre-Completion Validation

Before marking a task 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 `git diff` that only intended changes were made

4. Check that both production AND test addons are updated (if applicable)

5. Confirm documentation matches the implementation

When Uncertain

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.