Migrate from deprecated Alexa Gadgets API to Home Assistant + MQTT

[Copilot]

Amazon deprecated the Alexa Gadgets Bluetooth API. This migrates to Home Assistant with Alexa Media Player integration + MQTT while preserving the natural voice UX.

Architecture

Echo Device → Home Assistant (Alexa Media Player) → MQTT → Pi Zero W → 7-Segment Display

Previous: Bluetooth pairing via deprecated Gadgets API
Current: HA polls timer state, publishes to MQTT topic

Changes

timer.py

• Replace AlexaGadget base class with paho-mqtt client
• Subscribe to echopitimer/timer topic for JSON messages
• Handle actions: set, update, cancel with unix timestamp end times
• Use threading.Event instead of boolean flag for responsive shutdown
• Display logic unchanged (countdown, HH:MM/MM:SS formatting, pulsing)

def _on_message(self, client, userdata, msg):
    payload = json.loads(msg.payload.decode())
    if payload['action'] == 'set':
        self.timer_end_time = payload['end_time']
        self.timer_active.set()
        threading.Thread(target=self._run_timer).start()

timer.ini

• Remove: amazonId, alexaGadgetSecret, GadgetCapabilities
• Add: broker_host, broker_port, topic, optional auth

homeassistant/automation_example.yaml

• Automation triggering on next_timer attribute changes
• Publishes JSON to MQTT with calculated unix timestamps
• Handles set/update/cancel detection

README.md

• Document HA + Alexa Media Player + Mosquitto setup
• Note: Requires separate device for HA (Pi Zero W insufficient)
• Alexa Media Player is community-maintained, not official

requirements.txt

• Pin paho-mqtt<2.0.0 (v2 deprecates mqtt.Client() constructor)
• Adafruit display libraries

User Experience

Unchanged. "Alexa, set a timer" → countdown on display.

Original prompt

Background

Amazon deprecated the Alexa Gadgets API, which this project relied on to receive timer events from Echo devices over Bluetooth. The app needs to be rewritten to work with current APIs while preserving the same user experience: saying "Alexa, set a timer" naturally, with no custom skills or special invocations.

New Architecture

Replace the Bluetooth Gadgets integration with Home Assistant + Alexa Media Player integration + MQTT:

"Alexa, set a 10 minute timer"
        │
        ▼
   Echo Device
        │
        ▼ (detected via Alexa Media Player integration polling)
Home Assistant
        │
        ▼ (MQTT publish)
   Raspberry Pi Zero W
        │
        ▼
  7-Segment Display

Changes Required

1. Rewrite timer.py

• Remove the from agt import AlexaGadget import and AlexaGadget base class dependency
• Replace with an MQTT listener using paho-mqtt
• The class should subscribe to a configurable MQTT topic (e.g., echopitimer/timer)
• Handle incoming JSON messages with actions like:
  • {"action": "set", "end_time": <unix_timestamp>} — start a timer countdown
  • {"action": "update", "end_time": <unix_timestamp>} — update a running timer's end time
  • {"action": "cancel"} — cancel the current timer and clear the display
• Keep ALL existing display logic intact, including:
  • _run_timer() countdown loop with 100ms sleep
  • _set_time_display() with HH:MM (blinking colon) for >1hr and MM:SS for <1hr
  • The pulse/brightness animation when timer expires
  • display.fill(0) to clear on cancel
  • Threading to prevent blocking
• Keep the Adafruit HT16K33 display initialization (board, busio, segments.BigSeg7x4)

2. Replace timer.ini with MQTT-oriented config

• Remove amazonId and alexaGadgetSecret fields
• Remove GadgetCapabilities section
• Add MQTT configuration:
  • broker_host (default: localhost)
  • broker_port (default: 1883)
  • topic (default: echopitimer/timer)
  • Optional: username and password for MQTT auth

3. Add requirements.txt

Include the new Python dependencies:

• paho-mqtt
• adafruit-circuitpython-ht16k33
• adafruit-blinka
• python-dateutil

4. Add a sample Home Assistant automation YAML

Create a file like homeassistant/automation_example.yaml that shows users how to set up the HA automation to forward Alexa Media Player timer events to the MQTT topic. The automation should:

• Trigger on Alexa Media Player timer state changes (the next_timer attribute of the media player entity)
• Publish the appropriate JSON payload to the configured MQTT topic
• Handle timer set, update, and cancel events
• Include comments explaining how to customize entity names, MQTT topics, etc.

5. Update README.md

• Remove the "DEPRECATED" notice at the top
• Update the architecture description to explain the new HA + MQTT approach
• Keep all the hardware setup instructions (Pi setup, wiring, I2C, etc.) — those are unchanged
• Replace the "Configuration of Alexa Gadget" section with new sections covering:
  • Home Assistant installation and Alexa Media Player integration setup
  • MQTT broker (Mosquitto) setup
  • Configuring timer.ini with MQTT settings
  • Installing the HA automation
• Update the "Code details" section to reflect the new MQTT-based architecture
• Note that a separate device is needed to run Home Assistant (the Pi Zero W is too underpowered)
• Mention that the Alexa Media Player integration is unofficial/community-maintained

Important Notes

• The display hardware and wiring are completely unchanged
• The core timer display logic should remain as close to the original as possible
• The user experience remains the same: "Alexa, set a timer" just works, with the countdown shown on the 7-segment display

This pull request was created from Copilot chat.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.