iqrfpy.utils.dpa

  1"""DPA utility module.
  2
  3This module contains DPA constants and enum classes.
  4"""
  5
  6from .enums import IntEnumMember
  7
  8__all__ = (
  9    'RequestPacketMembers',
 10    'ResponsePacketMembers',
 11    'COORDINATOR_NADR',
 12    'NADR_MIN',
 13    'NADR_MAX',
 14    'NODE_NADR_MIN',
 15    'NODE_NADR_MAX',
 16    'IQUIP_NADR',
 17    'PNUM_USER_MIN',
 18    'PNUM_USER_MAX',
 19    'PNUM_MAX',
 20    'REQUEST_PCMD_MIN',
 21    'REQUEST_PCMD_MAX',
 22    'RESPONSE_PCMD_MIN',
 23    'RESPONSE_PCMD_MAX',
 24    'HWPID_MIN',
 25    'HWPID_MAX',
 26    'CONFIRMATION_PACKET_LEN',
 27    'RESPONSE_GENERAL_LEN',
 28    'THERMOMETER_SENSOR_ERROR',
 29    'THERMOMETER_RESOLUTION',
 30    'MID_MIN',
 31    'MID_MAX',
 32    'LOCAL_DEVICE_ADDR',
 33    'IQMESH_TEMP_ADDR',
 34    'BROADCAST_ADDR',
 35    'BYTE_MIN',
 36    'BYTE_MAX',
 37    'WORD_MIN',
 38    'WORD_MAX',
 39    'PDATA_MAX_LEN',
 40    'EEEPROM_WRITE_MAX_DATA_LEN',
 41    'EEPROM_WRITE_MAX_DATA_LEN',
 42    'RAM_WRITE_MAX_DATA_LEN',
 43    'BACKUP_DATA_BLOCK_MAX_LEN',
 44    'SELECTED_NODES_LEN',
 45    'BINOUT_INDEX_MIN',
 46    'BINOUT_INDEX_MAX',
 47    'SENSOR_INDEX_MIN',
 48    'SENSOR_INDEX_MAX',
 49    'BaudRates',
 50    'ResponseCodes',
 51    'PeripheralTypes',
 52    'ExtendedPeripheralCharacteristics',
 53    'FrcCommands',
 54    'UserFrcCommands',
 55    'FrcResponseTimes',
 56    'IoConstants',
 57    'TrConfByteAddrs',
 58    'TrConfBitMasks',
 59    'OsLoadCodeAction',
 60    'OsLoadCodeType',
 61    'OsLoadCodeErrors',
 62    'OsLoadCodeResult',
 63    'McuTypes',
 64    'TrDTypes',
 65    'TrGTypes',
 66    'RfBands',
 67)
 68
 69
 70class RequestPacketMembers(IntEnumMember):
 71    """Request packet member indices."""
 72
 73    NADR = 0
 74    PNUM = 2
 75    PCMD = 3
 76    HWPID_LO = 4
 77    HWPID_HI = 5
 78
 79
 80class ResponsePacketMembers(IntEnumMember):
 81    """Response packet member indices."""
 82
 83    NADR = 0
 84    PNUM = 2
 85    PCMD = 3
 86    HWPID_LO = 4
 87    HWPID_HI = 5
 88    RCODE = 6
 89    DPA_VALUE = 7
 90
 91
 92# general constants
 93COORDINATOR_NADR = NADR_MIN = 0
 94NODE_NADR_MIN = 0x01
 95NADR_MAX = NODE_NADR_MAX = 0xEF
 96IQUIP_NADR = 0xF0
 97PNUM_USER_MIN = 0x20
 98PNUM_USER_MAX = 0x3E
 99PNUM_MAX = 0x7F
100REQUEST_PCMD_MIN = 0
101REQUEST_PCMD_MAX = 0x7F
102RESPONSE_PCMD_MIN = 0x80
103RESPONSE_PCMD_MAX = 0xFF
104HWPID_MIN = 0
105HWPID_MAX = 0xFFFF
106
107# confirmation constants
108CONFIRMATION_PACKET_LEN = 11
109
110# response constants
111RESPONSE_GENERAL_LEN = 8
112
113# thermometer constants
114THERMOMETER_SENSOR_ERROR = 0x80
115THERMOMETER_RESOLUTION = 0.0625
116
117# mid constants
118MID_MIN = 0
119MID_MAX = 0xFFFFFFFF
120
121# other constants
122IBK_LEN = 16
123LOCAL_DEVICE_ADDR = 0xFC
124IQMESH_TEMP_ADDR = 0xFE
125BROADCAST_ADDR = 0xFF
126BYTE_MIN = 0
127BYTE_MAX = 255
128WORD_MIN = 0
129WORD_MAX = 65535
130
131PDATA_MAX_LEN = 56
132EEPROM_WRITE_MAX_DATA_LEN = 55
133EEEPROM_WRITE_MAX_DATA_LEN = 54
134RAM_WRITE_MAX_DATA_LEN = 55
135BACKUP_DATA_BLOCK_MAX_LEN = 49
136SELECTED_NODES_LEN = 30
137
138SENSOR_INDEX_MIN = BINOUT_INDEX_MIN = 0
139SENSOR_INDEX_MAX = BINOUT_INDEX_MAX = 31
140
141
142class BaudRates(IntEnumMember):
143    """UART baud rate constants."""
144
145    B1200 = 0
146    B2400 = 1
147    B4800 = 2
148    B9600 = 3
149    B19200 = 4
150    B38400 = 5
151    B57600 = 6
152    B115200 = 7
153    B230400 = 8
154
155
156# rcode constants
157class ResponseCodes(IntEnumMember):
158    """DPA response codes."""
159
160    OK = 0
161    ERROR_FAIL = 1
162    ERROR_PCMD = 2
163    ERROR_PNUM = 3
164    ERROR_ADDR = 4
165    ERROR_DATA_LEN = 5
166    ERROR_DATA = 6
167    ERROR_HWPID = 7
168    ERROR_NADR = 8
169    ERROR_IFACE_CUSTOM_HANDLER = 9
170    ERROR_MISSING_CUSTOM_DPA_HANDLER = 10
171    ERROR_USER_FROM = 0x20
172    ERROR_USER_TO = 0x3F
173    RESERVED_FLAG = 0x40
174    ASYNC_RESPONSE = 0x80
175    CONFIRMATION = 0xFF
176
177    def __str__(self):
178        """Convert self to representation of error code."""
179        return self.to_string(self.value)
180
181    @classmethod
182    def is_ok_response(cls, rcode: int) -> bool:
183        """Check if response code indicates OK response, including flags.
184
185        Args:
186            rcode (int): Response code to check.
187
188        Returns:
189            bool: True if response code indicates OK response, False otherwise.
190        """
191        return (rcode & ~cls.ASYNC_RESPONSE & ~cls.RESERVED_FLAG) == ResponseCodes.OK
192
193    @classmethod
194    def to_string(cls, value: int):
195        """Convert value to string representation of error code.
196
197        Args:
198            value (int): Value to convert
199        Returns:
200            :obj:`str`: String representation of error code
201        """
202        if not BYTE_MIN <= value <= BYTE_MAX:
203            return 'Invalid DPA response code'
204        if cls.ERROR_USER_FROM <= value <= cls.ERROR_USER_TO:
205            return 'User error code'
206        flags = []
207        if value != cls.CONFIRMATION:
208            if value & 0x40:
209                flags.append('reserved')
210                value -= 0x40
211            if value & 0x80:
212                flags.append('async')
213                value -= 0x80
214        if value not in cls:
215            return 'Unknown DPA response code'
216        val = cls(value)
217        str_val = None
218        match val:
219            case cls.OK:
220                str_val = 'No error'
221            case cls.ERROR_FAIL:
222                str_val = 'General fail'
223            case cls.ERROR_PCMD:
224                str_val = 'Incorrect PCMD'
225            case cls.ERROR_PNUM:
226                str_val = 'Incorrect PNUM or PCMD'
227            case cls.ERROR_ADDR:
228                str_val = 'Incorrect Address'
229            case cls.ERROR_DATA_LEN:
230                str_val = 'Incorrect Data length'
231            case cls.ERROR_DATA:
232                str_val = 'Incorrect Data'
233            case cls.ERROR_HWPID:
234                str_val = 'Incorrect HW Profile ID used'
235            case cls.ERROR_NADR:
236                str_val = 'Incorrect NADR'
237            case cls.ERROR_IFACE_CUSTOM_HANDLER:
238                str_val = 'Data from interface consumed by Custom DPA Handler'
239            case cls.ERROR_MISSING_CUSTOM_DPA_HANDLER:
240                str_val = 'Custom DPA Handler is missing'
241            case cls.CONFIRMATION:
242                str_val = 'DPA confirmation'
243        flag_str = '' if len(flags) == 0 else ''.join(f' [{flag}]' for flag in flags)
244        return f'{str_val}{flag_str}'
245
246
247class PeripheralTypes(IntEnumMember):
248    """Peripheral type constants."""
249
250    PERIPHERAL_TYPE_DUMMY = 0
251    PERIPHERAL_TYPE_COORDINATOR = 1
252    PERIPHERAL_TYPE_NODE = 2
253    PERIPHERAL_TYPE_OS = 3
254    PERIPHERAL_TYPE_EEPROM = 4
255    PERIPHERAL_TYPE_BLOCK_EEPROM = 5
256    PERIPHERAL_TYPE_RAM = 6
257    PERIPHERAL_TYPE_LED = 7
258    PERIPHERAL_TYPE_SPI = 8
259    PERIPHERAL_TYPE_IO = 9
260    PERIPHERAL_TYPE_UART = 10
261    PERIPHERAL_TYPE_THERMOMETER = 11
262    PERIPHERAL_TYPE_FRC = 14
263
264
265class ExtendedPeripheralCharacteristics(IntEnumMember):
266    """Extended peripheral characteristics constants."""
267
268    PERIPHERAL_TYPE_EXTENDED_DEFAULT = 0
269    PERIPHERAL_TYPE_EXTENDED_READ = 1
270    PERIPHERAL_TYPE_EXTENDED_WRITE = 2
271    PERIPHERAL_TYPE_EXTENDED_READ_WRITE = 3
272
273
274class FrcCommands(IntEnumMember):
275    """FRC command intervals."""
276
277    FRC_2BIT_FROM = 0
278    FRC_2BIT_TO = 0x7F
279    FRC_1BYTE_FROM = 0x80
280    FRC_1BYTE_TO = 0xDF
281    FRC_2BYTE_FROM = 0xE0
282    FRC_2BYTE_TO = 0xF7
283    FRC_4BYTE_FROM = 0xF8
284    FRC_4BYTE_TO = 0xFF
285
286
287class UserFrcCommands(IntEnumMember):
288    """User FRC command intervals."""
289
290    USER_BIT_FROM = 0x40
291    USER_BIT_TO = 0x7F
292    USER_BYTE_FROM = 0xC0
293    USER_BYTE_TO = 0xDF
294    USER_2BYTE_FROM = 0xF0
295    USER_2BYTE_TO = 0xFF
296    USER_4BYTE_FROM = 0xFC
297    USER_4BYTE_TO = 0xFF
298
299
300class FrcResponseTimes(IntEnumMember):
301    """FRC response time constants."""
302
303    MS40 = 0
304    MS360 = 16
305    MS680 = 32
306    MS1320 = 48
307    MS2600 = 64
308    MS5160 = 80
309    MS10280 = 96
310    MS20520 = 112
311
312
313class IoConstants(IntEnumMember):
314    """IO peripheral constants enum."""
315
316    TRIS_A = PORT_A = 0x00
317    TRIS_B = PORT_B = 0x01
318    TRIS_C = PORT_C = 0x02
319    TRIS_E = PORT_E = 0x04
320    PULL_UP_A = 0x10
321    PULL_UP_B = 0x11
322    PULL_UP_C = 0x12
323    PULL_UP_E = 0x14
324    DELAY = 0xFF
325
326
327class TrConfByteAddrs(IntEnumMember):
328    """TR configuration memory block address enum."""
329
330    DPA_CONFIG_BITS_0 = 0x05
331    RF_OUTPUT_POWER = 0x08
332    RF_SIGNAL_FILTER = 0x09
333    LP_RF_TIMEOUT = 0x0A
334    UART_BAUD_RATE = 0x0B
335    ALTERNATIVE_DSM_CHANNEL = 0x0C
336    DPA_CONFIG_BITS_1 = 0x0D
337    RF_CHANNEL_A = 0x11
338    RF_CHANNEL_B = 0x12
339
340
341class TrConfBitMasks(IntEnumMember):
342    """TR configuration bits enum."""
343
344    CUSTOM_DPA_HANDLER = LOCAL_FRC = 1
345    DPA_PEER_TO_PEER = 2
346    ROUTING_OFF = 8
347    IO_SETUP = 16
348    USER_PEER_TO_PEER = 32
349    STAY_AWAKE_WHEN_NOT_BONDED = 64
350    STD_AND_LP_NETWORK = 128
351
352
353class OsLoadCodeAction(IntEnumMember):
354    """OS Load Code flags action enum."""
355
356    VERIFY = 0
357    VERIFY_AND_LOAD = 1
358
359
360class OsLoadCodeType(IntEnumMember):
361    """OS Load Code flags code type enum."""
362
363    CUSTOM_DPA_HANDLER = 0
364    IQRF_PLUGIN = 1
365    IQRF_OS_CHANGE_FILE = 2
366
367
368class OsLoadCodeResult(IntEnumMember):
369    """OS Load Code result enum."""
370
371    ERROR = 0
372    NO_ERROR = 1
373
374
375class OsLoadCodeErrors(IntEnumMember):
376    """OS Load Code error enum."""
377
378    RESERVED = -1
379    HEX_IQRF_CHECKSUM_MISMATCH = 0
380    OLD_OS_MISSING = 3
381    IQRF_OS_CHANGE_CHECKSUM_MISMATCH = 4
382    UNSUPPORTED_IQRF_OS_VERSION = 7
383
384
385class McuTypes(IntEnumMember):
386    """TR module MCU types enum."""
387
388    PIC16LF1938 = 4
389    PIC16LF18877 = 5
390
391    def __str__(self):
392        """String representation of MCU type as module code.
393
394        PIC16LF1938 => D
395        PIC16LF18877 => G
396
397        Returns:
398            str: MCU type code.
399        """
400        match self.value:
401            case self.PIC16LF1938:
402                return 'D'
403            case self.PIC16LF18877:
404                return 'G'
405
406    @classmethod
407    def get_mcu_code_str(cls, value: int) -> str:
408        """Return MCU code associated with its type.
409
410        Args:
411            value (int): Value to get MCU code from.
412
413        Returns:
414            str: MCU code associated with its type ('D' for PIC16LF1938, 'G' for PIC16LF18877, or '?' for unknown).
415        """
416        if value in cls:
417            return str(cls(value))
418        else:
419            return '?'
420
421
422class TrDTypes(IntEnumMember):
423    """TR module D types enum."""
424
425    TR_52D = 0
426    TR_58D_RJ = 1
427    TR_72D = 2
428    TR_53D = 3
429    TR_78D = 4
430    TR_54D = 8
431    TR_55D = 9
432    TR_56D = 10
433    TR_76D = 11
434    TR_77D = 12
435    TR_75D = 13
436
437    def __str__(self):
438        """String representation of TR D type.
439
440        TR_72D => TR-72D
441
442        Returns:
443           str: TR D type string.
444        """
445        return self.name.replace('_', '-')
446
447    @classmethod
448    def get_tr_series_str(cls, value: int) -> str:
449        """Return TR D series string from integer value.
450
451        Args:
452            value (int): Value to get TR D series from.
453
454        Returns:
455            str: TR D series string.
456        """
457        if value in cls:
458            return str(cls(value))
459        else:
460            return 'Unknown'
461
462
463class TrGTypes(IntEnumMember):
464    """TR module G types enum."""
465
466    TR_82G = 0
467    TR_72G = 2
468    TR_85G = 9
469    TR_86G = 10
470    TR_76G = 11
471    TR_75G = 13
472
473    def __str__(self):
474        """String representation of TR G type.
475
476        TR_82G => TR-82G
477
478        Returns:
479            str: TR G type string.
480        """
481        return self.name.replace('_', '-')
482
483    @classmethod
484    def get_tr_series_str(cls, value: int) -> str:
485        """Return TR G series string from integer value.
486
487        Args:
488            value (int): Value to get TR G series from.
489
490        Returns:
491            str: TR G series string.
492        """
493        if value in cls:
494            return str(cls(value))
495        else:
496            return 'Unknown'
497
498
499class RfBands(IntEnumMember):
500    """RF bands enum."""
501
502    RF_BAND_868 = 0
503    RF_BAND_916 = 1
504    RF_BAND_433 = 2
505    RF_BAND_RESERVED = 3
506
507    def __str__(self):
508        """Convert to human-readable string representation.
509
510        Example format 868 MHz.
511
512        Returns:
513            str: Human-readable RF Band string
514        """
515        if self.name == self.RF_BAND_RESERVED.name:
516            return 'Reserved'
517        return f'{self.name[8:]} MHz'