Skip to content

Commit 6cb2b0f

Browse files
committed
docs: udpdate docs
1 parent e118e3f commit 6cb2b0f

1 file changed

Lines changed: 195 additions & 0 deletions

File tree

‎docs/SIGNALDUINO_MIGRATION_PLAN.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@
1414
- Replace Perl-only helpers with Python equivalents that rely on `sd_protocols` (e.g. `length_in_range`, `postDemodulation`, `mcBit2*` handlers).
1515
3. **Dispatch/events**
1616
- Provide Python callbacks (instead of FHEM `Dispatch`) so that decoded frames can be consumed by higher-level code (e.g. MQTT bridge, tests, etc.).
17+
4. **Firmware Management**
18+
- Port the firmware update logic: fetching releases from GitHub, downloading artifacts, and flashing via `avrdude`.
1719

1820
## Proposed Python Package Layout
1921
```
@@ -31,6 +33,7 @@ signalduino/
3133
│ ├── mu.py # Port of SIGNALduino_Parse_MU
3234
│ ├── mc.py # Port of SIGNALduino_Parse_MC
3335
│ └── mn.py # Port of SIGNALduino_Parse_MN
36+
├── firmware.py # Firmware update logic (GitHub API, download, flash)
3437
└── controller.py # High-level SignalduinoDevice orchestrating transport, parser, queue, keepalive
3538
```
3639

@@ -44,6 +47,10 @@ signalduino/
4447
- keepalive timer and automatic reconnects similar to `SIGNALduino_KeepAlive` + `SIGNALduino_Ready`
4548
- callback registration for decoded frames & raw events
4649
- `parser/*`: Pure functions/classes that accept a `SDProtocols` instance, raw firmware line, and return zero or more `DecodedMessage` objects with metadata (protocol id, RSSI, freq AFC, raw message). These modules port `SIGNALduino_Split_Message`, pattern lookup helpers, etc., but use Python data structures and `sd_protocols` helpers.
50+
- `firmware.py`: Handles firmware updates.
51+
- `check_for_updates(hardware, channel)`: Queries GitHub releases.
52+
- `download_firmware(url, target_path)`: Downloads the .hex file.
53+
- `flash_firmware(device_path, hex_file, hardware_type, flash_command)`: Invokes `avrdude` (or other tools) to flash the device. Handles special reset logic (e.g. Radino 1200 baud touch).
4754

4855
## High-Level Data Flow
4956
```mermaid
@@ -94,6 +101,21 @@ flowchart LR
94101
3. Responses are correlated via simple matchers (regex or lambda) derived from the Perl `%gets` table.
95102
4. Keepalive schedules periodic `ping` commands. If `SDUINO_KEEPALIVE_MAXRETRY` is exceeded, the controller tears down and reconnects.
96103

104+
## Firmware Update Strategy
105+
| Perl Source | Python Target | Notes |
106+
|-------------|---------------|-------|
107+
| `SIGNALduino_querygithubreleases` | `firmware.fetch_releases` | Use `requests` or `aiohttp` to query GitHub API. |
108+
| `SIGNALduino_githubParseHttpResponse` | `firmware.parse_releases` | Parse JSON, filter by hardware/channel (stable/testing). |
109+
| `SIGNALduino_Set_flash` | `controller.flash_firmware` | Entry point. Orchestrates download + flash. |
110+
| `SIGNALduino_ParseHttpResponse` (flash part) | `firmware.download_file` | Download logic. |
111+
| `SIGNALduino_PrepareFlash` | `firmware.prepare_flash_command` | Construct `avrdude` command string. Handle Radino reset (1200 baud). |
112+
| `SIGNALduino_avrdude` | `firmware.execute_flash` | Run `subprocess.run` for `avrdude`. |
113+
114+
**Hardware Types to Support:**
115+
- `nano328`, `nanoCC1101` (Standard `avrdude -c arduino`)
116+
- `radinoCC1101` (Special `avrdude -c avr109`, requires 1200 baud reset)
117+
- `ESP32`/`ESP8266` (Currently Perl says "not supported via module", but we should design interfaces to allow `esptool` in future).
118+
97119
## Testing Approach
98120
- **Parser unit tests**: feed captured raw frames from Perl repo (`temp_repo/t/...`) into the Python parsers and assert decoded payloads. These tests do not require hardware.
99121
- **Transport/controller tests**: use `socket.socketpair()` / `io.BytesIO` doubles to simulate firmware responses, ensuring queue timing, keepalive, and callbacks work deterministically.
@@ -104,3 +126,176 @@ flowchart LR
104126
2. Implement `transport.py` and `controller.py` skeletons (with dependency injection for easier testing).
105127
3. Port `SIGNALduino_Split_Message` helpers into Python and start with the MC parser (it has the least dependency on lookup tables).
106128
4. Replace Perl-style dispatching with callback registration and build pytest coverage around the new parsers.
129+
130+
---
131+
132+
# Migration Status Matrix
133+
134+
This section lists all subroutines from the original Perl implementation (`00_SIGNALduino.pm` and `SD_Protocols.pm`) and their corresponding migration status in the Python project.
135+
136+
## 00_SIGNALduino.pm
137+
138+
| Perl Subroutine | Python Implementation | Status | Notes |
139+
| :--- | :--- | :--- | :--- |
140+
| `SIGNALduino_Initialize` | `signalduino.controller.SignalduinoController.__init__` | ✅ Migrated | Initialization logic |
141+
| `SIGNALduino_Define` | `signalduino.controller.SignalduinoController.__init__` | ✅ Migrated | Setup and configuration |
142+
| `SIGNALduino_Connect` | `signalduino.controller.SignalduinoController.connect` | ✅ Migrated | Connection handling |
143+
| `SIGNALduino_Disconnect` | `signalduino.controller.SignalduinoController.disconnect` | ✅ Migrated | Disconnection handling |
144+
| `SIGNALduino_Read` | `signalduino.transport.BaseTransport.readline` | ✅ Migrated | Transport layer reading |
145+
| `SIGNALduino_Write` | `signalduino.transport.BaseTransport.write_line` | ✅ Migrated | Transport layer writing |
146+
| `SIGNALduino_SimpleWrite` | `signalduino.controller.SignalduinoController.send_command` | ✅ Migrated | Simple command sending |
147+
| `SIGNALduino_Parse` | `signalduino.parser.__init__.SignalParser.parse_line` | ✅ Migrated | Main parsing entry point |
148+
| `SIGNALduino_Parse_MC` | `signalduino.parser.mc.MCParser.parse` | ✅ Migrated | Manchester parsing |
149+
| `SIGNALduino_Parse_MS` | `signalduino.parser.ms.MSParser.parse` | ✅ Migrated | Message Synced parsing |
150+
| `SIGNALduino_Parse_MU` | `signalduino.parser.mu.MUParser.parse` | ✅ Migrated | Message Unsynced parsing |
151+
| `SIGNALduino_Parse_MN` | `signalduino.parser.mn.MNParser.parse` | ✅ Migrated | Message Noise parsing |
152+
| `SIGNALduino_Set_MessageType` | `signalduino.controller.SignalduinoController.set_message_type_enabled` | ✅ Migrated | Enable/disable message types |
153+
| `SIGNALduino_Set_Freq` | `signalduino.controller.SignalduinoController.set_freq` | ✅ Migrated | Frequency setting |
154+
| `SIGNALduino_Log3` | `logging` module | ✅ Migrated | Standard Python logging used |
155+
| `SIGNALduino_HandleWriteQueue` | `signalduino.controller.SignalduinoController._writer_loop` | ✅ Migrated | Queue processing |
156+
| `SIGNALduino_ResetDevice` | N/A | ❌ Pending | Device reset logic |
157+
| `SIGNALduino_CloseDevice` | `signalduino.transport.BaseTransport.close` | ✅ Migrated | Closing device connection |
158+
| `SIGNALduino_DoInit` | N/A | ❌ Pending | Initialization sequence |
159+
| `SIGNALduino_StartInit` | N/A | ❌ Pending | Start initialization |
160+
| `SIGNALduino_KeepAlive` | N/A | ❌ Pending | Keep-alive mechanism |
161+
| `SIGNALduino_calcRSSI` | `signalduino.parser.base.calc_rssi` | ✅ Migrated | RSSI calculation |
162+
| `SIGNALduino_Attr` | N/A | ❌ Pending | Attribute handling (FHEM specific) |
163+
| `SIGNALduino_Set` | N/A | ❌ Pending | Generic Set command |
164+
| `SIGNALduino_Get` | N/A | ❌ Pending | Generic Get command |
165+
| `SIGNALduino_Shutdown` | N/A | ❌ Pending | Shutdown handling |
166+
| `SIGNALduino_Undef` | N/A | ❌ Pending | Undefine device |
167+
| `SIGNALduino_FingerprintFn` | N/A | ❌ Pending | Fingerprinting |
168+
| `SIGNALduino_Set_FhemWebList` | N/A | ❌ Pending | FHEM Web interaction |
169+
| `SIGNALduino_Set_raw` | N/A | ❌ Pending | Send raw command |
170+
| `SIGNALduino_Set_flash` | N/A | ❌ Pending | Flash firmware |
171+
| `SIGNALduino_Set_reset` | N/A | ❌ Pending | Reset command |
172+
| `SIGNALduino_Attr_rfmode` | N/A | ❌ Pending | RF Mode attribute |
173+
| `SIGNALduino_Set_sendMsg` | N/A | ❌ Pending | Send message command |
174+
| `SIGNALduino_Set_close` | N/A | ❌ Pending | Close command |
175+
| `SIGNALduino_Set_bWidth` | N/A | ❌ Pending | Bandwidth setting |
176+
| `SIGNALduino_Set_LaCrossePairForSec` | N/A | ❌ Pending | LaCrosse pairing |
177+
| `SIGNALduino_Get_Callback` | N/A | ❌ Pending | Get callback |
178+
| `SIGNALduino_Get_FhemWebList` | N/A | ❌ Pending | Get FHEM Web list |
179+
| `SIGNALduino_Get_availableFirmware` | N/A | ❌ Pending | Get available firmware |
180+
| `SIGNALduino_Get_Command` | N/A | ❌ Pending | Get command |
181+
| `SIGNALduino_Get_Command_CCReg` | N/A | ❌ Pending | Get CC register |
182+
| `SIGNALduino_Get_RawMsg` | N/A | ❌ Pending | Get raw message |
183+
| `SIGNALduino_GetResponseUpdateReading` | N/A | ❌ Pending | Update reading from response |
184+
| `SIGNALduino_Get_delayed` | N/A | ❌ Pending | Delayed get |
185+
| `SIGNALduino_CheckUptimeResponse` | N/A | ❌ Pending | Check uptime |
186+
| `SIGNALduino_CheckCmdsResponse` | N/A | ❌ Pending | Check commands response |
187+
| `SIGNALduino_CheckccConfResponse` | N/A | ❌ Pending | Check CC config response |
188+
| `SIGNALduino_CheckccPatableResponse` | N/A | ❌ Pending | Check PA table response |
189+
| `SIGNALduino_CheckCcregResponse` | N/A | ❌ Pending | Check CC register response |
190+
| `SIGNALduino_CheckSendRawResponse` | N/A | ❌ Pending | Check send raw response |
191+
| `SIGNALduino_SimpleWrite_XQ` | N/A | ❌ Pending | Simple write XQ |
192+
| `SIGNALduino_CheckVersionResp` | N/A | ❌ Pending | Check version response |
193+
| `SIGNALduino_CheckCmdResp` | N/A | ❌ Pending | Check command response |
194+
| `SIGNALduino_XmitLimitCheck` | N/A | ❌ Pending | Transmit limit check |
195+
| `SIGNALduino_AddSendQueue` | N/A | ❌ Pending | Add to send queue |
196+
| `SIGNALduino_SendFromQueue` | N/A | ❌ Pending | Send from queue |
197+
| `SIGNALduino_ParseHttpResponse` | N/A | ❌ Pending | Parse HTTP response |
198+
| `SIGNALduino_splitMsg` | N/A | ❌ Pending | Split message |
199+
| `SIGNALduino_inTol` | N/A | ❌ Pending | Tolerance check |
200+
| `SIGNALduino_FillPatternLookupTable` | N/A | ❌ Pending | Fill pattern table |
201+
| `SIGNALduino_PatternExists` | `sd_protocols.pattern_utils.pattern_exists` | ✅ Migrated | Pattern existence check |
202+
| `cartesian_product` | `sd_protocols.pattern_utils.cartesian_product` | ✅ Migrated | Cartesian product |
203+
| `SIGNALduino_MatchSignalPattern` | N/A | ❌ Pending | Match signal pattern |
204+
| `SIGNALduino_Split_Message` | N/A | ❌ Pending | Split message (variant) |
205+
| `SIGNALduno_Dispatch` | N/A | ❌ Pending | Dispatch message |
206+
| `SIGNALduino_moduleMatch` | N/A | ❌ Pending | Module match |
207+
| `SIGNALduino_padbits` | N/A | ❌ Pending | Pad bits |
208+
| `SIGNALduino_WriteInit` | N/A | ❌ Pending | Write initialization |
209+
| `SIGNALduino_FW_Detail` | N/A | ❌ Pending | Firmware detail |
210+
| `SIGNALduino_FW_saveWhitelist` | N/A | ❌ Pending | Save whitelist |
211+
| `SIGNALduino_IdList` | N/A | ❌ Pending | ID list |
212+
| `SIGNALduino_getAttrDevelopment` | N/A | ❌ Pending | Get dev attribute |
213+
| `SIGNALduino_callsub` | N/A | ❌ Pending | Call subroutine |
214+
| `SIGNALduino_filterMC` | N/A | ❌ Pending | Filter MC |
215+
| `SIGNALduino_filterSign` | N/A | ❌ Pending | Filter signature |
216+
| `SIGNALduino_compPattern` | N/A | ❌ Pending | Compare pattern |
217+
| `SIGNALduino_getProtocolList` | N/A | ❌ Pending | Get protocol list (controller) |
218+
| `SIGNALduino_createLogCallback` | N/A | ❌ Pending | Create log callback |
219+
| `SIGNALduino_FW_getProtocolList` | N/A | ❌ Pending | Get protocol list (FW) |
220+
| `SIGNALduino_querygithubreleases` | N/A | ❌ Pending | Query GitHub releases |
221+
| `SIGNALduino_githubParseHttpResponse` | N/A | ❌ Pending | Parse GitHub response |
222+
| `_limit_to_number` | N/A | ❌ Pending | Limit to number |
223+
| `_limit_to_hex` | N/A | ❌ Pending | Limit to hex |
224+
| `SetPatable` | N/A | ❌ Pending | Set PA table |
225+
| `SetRegisters` | N/A | ❌ Pending | Set registers |
226+
| `SetRegistersUser` | N/A | ❌ Pending | Set registers user |
227+
| `SetDataRate` | N/A | ❌ Pending | Set data rate |
228+
| `CalcDataRate` | N/A | ❌ Pending | Calculate data rate |
229+
| `SetDeviatn` | N/A | ❌ Pending | Set deviation |
230+
| `setrAmpl` | N/A | ❌ Pending | Set amplifier |
231+
| `GetRegister` | N/A | ❌ Pending | Get register |
232+
| `CalcbWidthReg` | N/A | ❌ Pending | Calculate bandwidth register |
233+
| `SetSens` | N/A | ❌ Pending | Set sensitivity |
234+
235+
236+
## lib/SD_Protocols.pm
237+
238+
| Perl Subroutine | Python Implementation | Status | Notes |
239+
| :--- | :--- | :--- | :--- |
240+
| `new` | `sd_protocols.sd_protocols.SDProtocols.__init__` | ✅ Migrated | Class constructor |
241+
| `LoadHashFromJson` | `sd_protocols.sd_protocols.SDProtocols._load_protocols` | ✅ Migrated | Load protocols from JSON |
242+
| `LoadHash` | N/A | ❌ Pending | Legacy load hash |
243+
| `protocolExists` | N/A | ❌ Pending | Check if protocol exists |
244+
| `getProtocolList` | N/A | ❌ Pending | Get list of protocols |
245+
| `getKeys` | `sd_protocols.sd_protocols.SDProtocols.get_keys` | ✅ Migrated | Get protocol keys |
246+
| `checkProperty` | N/A | ❌ Pending | Check protocol property |
247+
| `getProperty` | N/A | ❌ Pending | Get protocol property |
248+
| `getProtocolVersion` | N/A | ❌ Pending | Get protocol version |
249+
| `setDefaults` | `sd_protocols.sd_protocols.SDProtocols.set_defaults` | ✅ Migrated | Set default values |
250+
| `binStr2hexStr` | `sd_protocols.helpers.ProtocolHelpersMixin.bin_str_2_hex_str` | ✅ Migrated | Binary string to hex string |
251+
| `LengthInRange` | `sd_protocols.helpers.ProtocolHelpersMixin.length_in_range` | ✅ Migrated | Check length in range |
252+
| `mc2dmc` | `sd_protocols.helpers.ProtocolHelpersMixin.mc2dmc` | ✅ Migrated | Manchester to differential Manchester |
253+
| `mcBit2Funkbus` | `sd_protocols.manchester.ManchesterMixin.mcBit2Funkbus` | ✅ Migrated | Funkbus protocol |
254+
| `MCRAW` | `sd_protocols.helpers.ProtocolHelpersMixin.mcraw` | ✅ Migrated | Raw Manchester processing |
255+
| `mcBit2Sainlogic` | `sd_protocols.manchester.ManchesterMixin.mcBit2Sainlogic` | ✅ Migrated | Sainlogic protocol |
256+
| `registerLogCallback` | `sd_protocols.sd_protocols.SDProtocols.register_log_callback` | ✅ Migrated | Log callback registration |
257+
| `_logging` | `sd_protocols.sd_protocols.SDProtocols._logging` | ✅ Migrated | Internal logging helper |
258+
| `dec2binppari` | `sd_protocols.helpers.ProtocolHelpersMixin.dec_2_bin_ppari` | ✅ Migrated | Decimal to binary with parity |
259+
| `mcBit2AS` | `sd_protocols.manchester.ManchesterMixin.mcBit2AS` | ✅ Migrated | AS protocol |
260+
| `mcBit2Grothe` | `sd_protocols.manchester.ManchesterMixin.mcBit2Grothe` | ✅ Migrated | Grothe protocol |
261+
| `mcBit2Hideki` | `sd_protocols.manchester.ManchesterMixin.mcBit2Hideki` | ✅ Migrated | Hideki protocol |
262+
| `mcBit2Maverick` | `sd_protocols.manchester.ManchesterMixin.mcBit2Maverick` | ✅ Migrated | Maverick protocol |
263+
| `mcBit2OSV1` | `sd_protocols.manchester.ManchesterMixin.mcBit2OSV1` | ✅ Migrated | OSV1 protocol |
264+
| `mcBit2OSV2o3` | `sd_protocols.manchester.ManchesterMixin.mcBit2OSV2o3` | ✅ Migrated | OSV2/3 protocol |
265+
| `mcBit2OSPIR` | `sd_protocols.manchester.ManchesterMixin.mcBit2OSPIR` | ✅ Migrated | OSPIR protocol |
266+
| `mcBit2SomfyRTS` | `sd_protocols.manchester.ManchesterMixin.mcBit2SomfyRTS` | ✅ Migrated | Somfy RTS protocol |
267+
| `mcBit2TFA` | `sd_protocols.manchester.ManchesterMixin.mcBit2TFA` | ✅ Migrated | TFA protocol |
268+
| `postDemo_EM` | `sd_protocols.postdemodulation.PostdemodulationMixin.postDemo_EM` | ✅ Migrated | EM post-demodulation |
269+
| `postDemo_Revolt` | `sd_protocols.postdemodulation.PostdemodulationMixin.postDemo_Revolt` | ✅ Migrated | Revolt post-demodulation |
270+
| `postDemo_FS20` | `sd_protocols.postdemodulation.PostdemodulationMixin.postDemo_FS20` | ✅ Migrated | FS20 post-demodulation |
271+
| `postDemo_FHT80` | `sd_protocols.postdemodulation.PostdemodulationMixin.postDemo_FHT80` | ✅ Migrated | FHT80 post-demodulation |
272+
| `postDemo_FHT80TF` | `sd_protocols.postdemodulation.PostdemodulationMixin.postDemo_FHT80TF` | ✅ Migrated | FHT80TF post-demodulation |
273+
| `postDemo_WS2000` | `sd_protocols.postdemodulation.PostdemodulationMixin.postDemo_WS2000` | ✅ Migrated | WS2000 post-demodulation |
274+
| `postDemo_WS7035` | `sd_protocols.postdemodulation.PostdemodulationMixin.postDemo_WS7035` | ✅ Migrated | WS7035 post-demodulation |
275+
| `postDemo_WS7053` | `sd_protocols.postdemodulation.PostdemodulationMixin.postDemo_WS7053` | ✅ Migrated | WS7053 post-demodulation |
276+
| `postDemo_lengtnPrefix` | `sd_protocols.postdemodulation.PostdemodulationMixin.postDemo_lengtnPrefix` | ✅ Migrated | Length prefix post-demodulation |
277+
| `Convbit2Arctec` | N/A | ❌ Pending | Convert bits to Arctec |
278+
| `Convbit2itv1` | N/A | ❌ Pending | Convert bits to ITV1 |
279+
| `ConvHE800` | N/A | ❌ Pending | Convert HE800 |
280+
| `ConvHE_EU` | N/A | ❌ Pending | Convert HE EU |
281+
| `ConvITV1_tristateToBit` | N/A | ❌ Pending | Convert ITV1 tristate |
282+
| `PreparingSend_FS20_FHT` | N/A | ❌ Pending | Prepare send FS20/FHT |
283+
| `ConvBresser_5in1` | `sd_protocols.helpers.ProtocolHelpersMixin.ConvBresser_5in1` | ✅ Migrated | Bresser 5in1 conversion |
284+
| `ConvBresser_6in1` | `sd_protocols.helpers.ProtocolHelpersMixin.ConvBresser_6in1` | ✅ Migrated | Bresser 6in1 conversion |
285+
| `ConvBresser_7in1` | `sd_protocols.helpers.ProtocolHelpersMixin.ConvBresser_7in1` | ✅ Migrated | Bresser 7in1 conversion |
286+
| `ConvBresser_lightning` | `sd_protocols.helpers.ProtocolHelpersMixin.ConvBresser_lightning` | ✅ Migrated | Bresser lightning conversion |
287+
| `LFSR_digest16` | `sd_protocols.helpers.ProtocolHelpersMixin.lfsr_digest16` | ✅ Migrated | LFSR digest 16 |
288+
| `ConvPCA301` | `sd_protocols.helpers.ProtocolHelpersMixin.ConvPCA301` | ✅ Migrated | PCA301 conversion |
289+
| `ConvKoppFreeControl` | `sd_protocols.helpers.ProtocolHelpersMixin.ConvKoppFreeControl` | ✅ Migrated | Kopp FreeControl conversion |
290+
| `ConvLaCrosse` | `sd_protocols.helpers.ProtocolHelpersMixin.ConvLaCrosse` | ✅ Migrated | LaCrosse conversion |
291+
| `PreparingSend_KOPP_FC` | N/A | ❌ Pending | Prepare send Kopp FC |
292+
| `_checkInvocant` | N/A | ❌ Pending | Internal helper |
293+
| `STORABLE_freeze` | N/A | ❌ Pending | Storable serialization |
294+
| `STORABLE_thaw` | N/A | ❌ Pending | Storable deserialization |
295+
| `_calc_crc16` | `sd_protocols.helpers.ProtocolHelpersMixin._calc_crc16` | ✅ Migrated | CRC16 Calculation |
296+
| `_calc_crc8_la_crosse` | `sd_protocols.helpers.ProtocolHelpersMixin._calc_crc8_la_crosse` | ✅ Migrated | CRC8 LaCrosse Calculation |
297+
298+
### Legend
299+
- ✅ **Migrated**: Functionality exists in the Python codebase.
300+
- ❌ **Pending**: Functionality has not yet been ported or verified.
301+
- N/A: Not directly applicable or structural change (e.g., class constructor vs. module level sub).

0 commit comments

Comments
 (0)