Transmitter
:::info Status
Implemented (core registry, claim, config, commands, health) — reflects docs/device-management-architecture-summary.md's "transmitter half mature" assessment. Hardware/broker-scale decisions below are explicitly Planned/Proposed.
:::
A transmitter is a mosque-installed, Azan360-owned device that drives the
mosque's amplifier — it plays received broadcasts through the mosque's PA
system, and (optionally) can capture live audio itself and push it into a
broadcast. It has no owner — see
Ownership — so its authorization
chain is simpler than a stream player's: registry + ACTIVE + inventory +
mosque assignment is sufficient, with no membership check.
What it does
| Capability | Detail |
|---|---|
| Plays broadcasts | Receives play commands over MQTT, streams the Icecast mount through the mosque's PA |
| Captures live audio (opt-in, per unit) | A dedicated authenticated WebSocket uplink — not MQTT — feeds the same FFmpeg → Icecast pipeline any live broadcast uses. See MQTT — Transmitter Audio Uplink |
| Reports presence/health | LWT + heartbeat + stale detection via core/device_status.py, core/device_alerts.py |
Registry (transmitter-facing) API
mosque_devices.py, reused as-is per the architecture summary's "Reuse"
verdict — identity, provisioning flows, setup codes, retained config, and
versioning all shipped:
| Method | Path | Purpose |
|---|---|---|
GET/POST | /api/v1/mosque-devices/mosque/{mosque_id} | List / register transmitters for a mosque |
GET | /api/v1/mosque-devices/pending | Approval queue |
GET/PATCH | /api/v1/mosque-devices/{device_id} | Detail / edit |
DELETE | /api/v1/mosque-devices/{device_id} | Remove |
POST | /api/v1/mosque-devices/{device_id}/cmd | Send a device command |
POST | /api/v1/mosque-devices/{device_id}/force-claim | Superadmin override of a stuck claim |
POST | /api/v1/mosque-devices/{device_id}/regenerate-setup-code | New pairing code |
POST | /api/v1/mosque-devices/{device_id}/regenerate-broadcast-secret | New audio-uplink credential (see Audio Uplink) |
POST | /api/v1/mosque-devices/{device_id}/maintenance | Maintenance mode |
POST | /api/v1/mosque-devices/{device_id}/factory-reset | Reset |
POST | /api/v1/mosque-devices/claim | Field claim |
POST | /api/v1/mosque-devices/announce | Field announce |
GET | /api/v1/mosque-devices/{device_id}/events | Event history |
GET | /api/v1/mosque-devices/{device_id}/health | Uptime, heartbeat, last azaan, errors |
GET/PUT | /api/v1/mosque-devices/recommended-firmware | Fleet-wide recommended firmware pointer |
Lifecycle, binding, and authorization behavior is the shared model — see Device Lifecycle and Device Authorization. Full endpoints for inventory/transitions/approval live under the unified registry: see Device Management module.
Wire protocol
Topic structure, commands, events, and retained config: MQTT Protocol.
Planned / Proposed — not yet decided
Per docs/device-management-architecture-summary.md's "Needs a Decision"
table, these are open, not implemented behavior:
| Item | Status | Note |
|---|---|---|
| BOM freeze — receiver part (A2DP + network audio concurrently, secure boot, anti-rollback, A/B OTA) | Proposed | Blocks all firmware work once frozen; cannot be retrofitted |
| Entitlement lease length (7 days proposed) | Proposed default | Must be tied to broker recovery time, not a standalone number — see Playback Entitlement |
| Broker deployment sizing / HA plan | Proposed | A single EMQX node suffices for the pilot; a named trigger (~2,000 units) needed for HA migration |
| Stream-token TTL (120s proposed) | Proposed | Needs confirmation against weak-link retry behavior |
Full sequencing: Roadmap — Transmitter.