iqrfpy.utils.common

  1"""Common utility module.
  2
  3common module provides utilities and auxiliary methods for
  4extraction of data from DPA bytes and Daemon API JSON messages.
  5"""
  6
  7__all__ = ['Common']
  8
  9import math
 10from typing import List, Optional, Union
 11from iqrfpy.enums.commands import *
 12from iqrfpy.enums.message_types import *
 13from iqrfpy.enums.peripherals import *
 14from iqrfpy.exceptions import InvalidPeripheralValueError, InvalidPeripheralCommandValueError, \
 15    JsonMsgidMissingError, JsonMTypeMissingError, JsonNadrMissingError, JsonHwpidMissingError, JsonRCodeMissingError, \
 16    JsonDpaValueMissingError, JsonResultMissingError, JsonStatusMissingError, JsonGenericDataMissingError, \
 17    UnsupportedMessageTypeError, UnsupportedPeripheralError, UnsupportedPeripheralCommandError
 18import iqrfpy.utils.dpa as dpa_constants
 19
 20
 21class Common:
 22    """Common class provides auxiliary methods for handling DPA and Daemon API JSON messages."""
 23
 24    # DPA
 25
 26    @staticmethod
 27    def serialize_to_dpa(nadr: int, pnum: Union[Peripheral, int], pcmd: Union[Command, int], hwpid: int = 0xFFFF,
 28                         pdata: Optional[List[int]] = None, mutable: bool = False):
 29        """Serialize request parameters into DPA packet.
 30
 31        Args:
 32            nadr (int): Device address
 33            pnum (Union[Peripheral, int]): Peripheral.
 34            pcmd (Union[Command, int]): Peripheral command.
 35            hwpid (int): Hardware profile ID. Defaults to 65535
 36            pdata (List[int], optional): Request data.
 37            mutable (bool, optional): Serialize into mutable byte representation of DPA request packet.
 38                Defaults to False.
 39
 40        Returns:
 41            :obj:`bytes`: Immutable byte representation of DPA request packet.\n
 42            :obj:`bytearray`: Mutable byte representation of DPA request packet (if argument mutable is True).
 43        """
 44        dpa: List[int] = [nadr, 0, pnum, pcmd, hwpid & 0xFF, (hwpid >> 8) & 0xFF]
 45        if pdata is not None:
 46            dpa.extend(pdata)
 47        if mutable:
 48            return bytearray(dpa)
 49        return bytes(dpa)
 50
 51    @staticmethod
 52    def hwpid_from_dpa(high: int, low: int) -> int:
 53        """Convert DPA HWPID bytes to a single 16bit unsigned integer.
 54
 55        Args:
 56            high (int): HWPID high byte
 57            low (int): HWPID low byte
 58        Returns:
 59            :obj:`int`: 16bit unsigned integer HWPID value
 60        Raises:
 61            ValueError: Raised if input values are not between 0 and 255
 62        """
 63        if high > dpa_constants.BYTE_MAX or low > dpa_constants.BYTE_MAX:
 64            raise ValueError('Argument value exceeds maximum allowed value of 255.')
 65        if high < dpa_constants.BYTE_MIN or low < dpa_constants.BYTE_MIN:
 66            raise ValueError('Negative argument values are not allowed.')
 67        return (high << 8) + low
 68
 69    @staticmethod
 70    def pnum_from_dpa(pnum: int) -> Union[Peripheral, int]:
 71        """Return peripheral enum value based on DPA peripheral data byte.
 72
 73        Args:
 74            pnum (int): Peripheral number data byte
 75        Returns:
 76            :obj:`Peripheral` or :obj:`int`: Peripheral enum member
 77        Raises:
 78            InvalidPeripheralValueError: Raised if pnum value is not between 0 and 255
 79            UnsupportedPeripheralError: Raised if pnum parameter value is not recognized as a member of any
 80                peripheral enum
 81        """
 82        if pnum < 0 or pnum > 255:
 83            raise InvalidPeripheralValueError('Peripheral value out of range 0-255.')
 84        if pnum in EmbedPeripherals:
 85            return EmbedPeripherals(pnum)
 86        if pnum in Standards:
 87            return Standards(pnum)
 88        if dpa_constants.PNUM_USER_MIN <= pnum <= dpa_constants.PNUM_USER_MAX:
 89            return pnum
 90        raise UnsupportedPeripheralError('Unknown or unsupported peripheral.')
 91
 92    @staticmethod
 93    def request_pcmd_from_dpa(pnum: Union[Peripheral, int], pcmd: int) -> Union[Command, int]:
 94        """Return request command based on DPA peripheral and command data byte.
 95
 96        Args:
 97            pnum (Union[Peripheral, int]): Peripheral enum member
 98            pcmd (int): Command data byte value
 99        Returns:
100            :obj:`Command` or :obj:`int`: Request command enum value
101        Raises:
102            InvalidPeripheralCommandValueError: Raised if pcmd is a negative value, or if pcmd is not a value
103                between 0 and 127
104            UnsupportedPeripheralError: Raised if pnum parameter value is not recognized as a member of any
105                peripheral enum
106            UnsupportedPeripheralCommandError: Raised if pcmd parameter value is not recognized as a member of any
107                peripheral command enum
108        """
109        if pcmd < dpa_constants.REQUEST_PCMD_MIN:
110            raise InvalidPeripheralCommandValueError('Negative peripheral command values are not allowed.')
111        if pcmd > dpa_constants.REQUEST_PCMD_MAX:
112            raise InvalidPeripheralCommandValueError('Peripheral command value exceeds maximum allowed value of 127.')
113        if dpa_constants.PNUM_USER_MIN <= pnum <= dpa_constants.PNUM_USER_MAX:
114            return pcmd
115        commands = None
116        match pnum:
117            case EmbedPeripherals.COORDINATOR:
118                commands = CoordinatorRequestCommands
119            case EmbedPeripherals.NODE:
120                commands = NodeRequestCommands
121            case EmbedPeripherals.OS:
122                commands = OSRequestCommands
123            case EmbedPeripherals.EEPROM:
124                commands = EEPROMRequestCommands
125            case EmbedPeripherals.EEEPROM:
126                commands = EEEPROMRequestCommands
127            case EmbedPeripherals.RAM:
128                commands = RAMRequestCommands
129            case EmbedPeripherals.LEDR | EmbedPeripherals.LEDG:
130                commands = LEDRequestCommands
131            case EmbedPeripherals.IO:
132                commands = IORequestCommands
133            case EmbedPeripherals.THERMOMETER:
134                commands = ThermometerRequestCommands
135            case EmbedPeripherals.UART:
136                commands = UartRequestCommands
137            case EmbedPeripherals.FRC:
138                commands = FrcRequestCommands
139            case EmbedPeripherals.EXPLORATION:
140                commands = ExplorationRequestCommands
141            case Standards.DALI:
142                commands = DALIRequestCommands
143            case Standards.BINARY_OUTPUT:
144                commands = BinaryOutputRequestCommands
145            case Standards.SENSOR:
146                commands = SensorRequestCommands
147            case Standards.LIGHT:
148                commands = LightRequestCommands
149            case _:
150                raise UnsupportedPeripheralError('Unknown or unsupported peripheral.')
151
152        if commands is not None and pcmd in commands:
153            return commands(pcmd)
154        raise UnsupportedPeripheralCommandError('Unknown or unsupported peripheral command.')
155
156    @staticmethod
157    def response_pcmd_from_dpa(pnum: Union[Peripheral, int], pcmd: int) -> Union[Command, int]:
158        """Return response command based on DPA peripheral and command data byte.
159
160        Args:
161            pnum (Union[Peripheral, int]): Peripheral enum member
162            pcmd (int): Command data byte value
163        Returns:
164            :obj:`Command` or :obj:`int`: Response command enum member
165        Raises:
166            InvalidPeripheralCommandValueError: Raised if pcmd is a negative value, or if pcmd is not a value
167                between 128 and 255
168            UnsupportedPeripheralError: Raised if pnum parameter value is not recognized as a member of any
169                peripheral enum
170            UnsupportedPeripheralCommandError: Raised if pcmd parameter value is not recognized as a member of any
171                peripheral command enum
172        """
173        if pcmd < dpa_constants.REQUEST_PCMD_MIN:
174            raise InvalidPeripheralCommandValueError('Negative peripheral command values are not allowed.')
175        if pcmd <= dpa_constants.REQUEST_PCMD_MAX or pcmd > dpa_constants.RESPONSE_PCMD_MAX:
176            raise InvalidPeripheralCommandValueError('Response peripheral command should be value between 128 and 255.')
177        if dpa_constants.PNUM_USER_MIN <= pnum <= dpa_constants.PNUM_USER_MAX:
178            return pcmd
179        commands = None
180        match pnum:
181            case EmbedPeripherals.COORDINATOR:
182                commands = CoordinatorResponseCommands
183            case EmbedPeripherals.NODE:
184                commands = NodeResponseCommands
185            case EmbedPeripherals.OS:
186                commands = OSResponseCommands
187            case EmbedPeripherals.EEPROM:
188                commands = EEPROMResponseCommands
189            case EmbedPeripherals.EEEPROM:
190                commands = EEEPROMResponseCommands
191            case EmbedPeripherals.RAM:
192                commands = RAMResponseCommands
193            case EmbedPeripherals.LEDR | EmbedPeripherals.LEDG:
194                commands = LEDResponseCommands
195            case EmbedPeripherals.IO:
196                commands = IOResponseCommands
197            case EmbedPeripherals.THERMOMETER:
198                commands = ThermometerResponseCommands
199            case EmbedPeripherals.UART:
200                commands = UartResponseCommands
201            case EmbedPeripherals.FRC:
202                commands = FrcResponseCommands
203            case EmbedPeripherals.EXPLORATION:
204                commands = ExplorationResponseCommands
205            case Standards.DALI:
206                commands = DALIResponseCommands
207            case Standards.BINARY_OUTPUT:
208                commands = BinaryOutputResponseCommands
209            case Standards.SENSOR:
210                commands = SensorResponseCommands
211            case Standards.LIGHT:
212                commands = LightResponseCommands
213            case _:
214                raise UnsupportedPeripheralError('Unknown or unsupported peripheral.')
215
216        if commands is not None and pcmd in commands:
217            return commands(pcmd)
218        raise UnsupportedPeripheralCommandError('Unknown or unsupported peripheral command.')
219
220    @staticmethod
221    def pdata_from_dpa(dpa: bytes) -> Union[List[int], None]:
222        """Return PDATA from DPA response bytes.
223
224        Args:
225            dpa (bytes): DPA response message
226        Returns:
227            :obj:`list` of :obj:`int` or :obj:`None`: PDATA integer list or None of there are no PDATA
228        """
229        if len(dpa) > 8:
230            return list(dpa[8:])
231        return None
232
233    @staticmethod
234    def parse_dpa_into_members(dpa: bytes):
235        """Parse DPA response into response members.
236
237        Args:
238            dpa (bytes): DPA response.
239
240        Returns:
241            :obj:`(int, int, int, int, int, int, Optional[List[int]])`: Response members
242        """
243        nadr = dpa[dpa_constants.ResponsePacketMembers.NADR]
244        pnum = dpa[dpa_constants.ResponsePacketMembers.PNUM]
245        pcmd = dpa[dpa_constants.ResponsePacketMembers.PCMD]
246        hwpid = Common.hwpid_from_dpa(
247            dpa[dpa_constants.ResponsePacketMembers.HWPID_HI],
248            dpa[dpa_constants.ResponsePacketMembers.HWPID_LO]
249        )
250        rcode = dpa[dpa_constants.ResponsePacketMembers.RCODE]
251        dpa_value = dpa[dpa_constants.ResponsePacketMembers.DPA_VALUE]
252        pdata = Common.pdata_from_dpa(dpa)
253        return nadr, pnum, pcmd, hwpid, rcode, dpa_value, pdata
254
255    # json
256
257    @staticmethod
258    def serialize_to_json(mtype: MessageType, msgid: str, nadr: int, hwpid: int = 0xFFFF, params: Optional[dict] = None,
259                          dpa_rsp_time: Optional[float] = None):
260        """Serialize request parameters into JSON API request object.
261
262        Args:
263            mtype (MessageType): Message type.
264            msgid (str): Message ID.
265            nadr (int): Device address.
266            hwpid (int): Hardware profile ID. Defaults to 65535.
267            params (dict, optional): Request parameters.
268            dpa_rsp_time (float, optional): Request timeout.
269
270        Returns:
271            :obj:`dict`: JSON-serialized request
272        """
273        params = params if params is not None else {}
274        json: dict = {
275            'mType': mtype.value,
276            'data': {
277                'msgId': msgid,
278                'req': {
279                    'nAdr': nadr,
280                    'hwpId': hwpid,
281                    'param': params,
282                },
283                'returnVerbose': True,
284            },
285        }
286        if dpa_rsp_time is not None:
287            json['data']['timeout'] = math.ceil(dpa_rsp_time * 1000)
288        return json
289
290    @staticmethod
291    def msgid_from_json(json: dict) -> str:
292        """Return response msgid from Daemon API JSON response.
293
294        Args:
295            json (dict): JSON API response
296        Returns:
297            :obj:`str`: JSON API response message ID
298        Raises:
299            JsonMsgidMissingError: Raised if Daemon API response does not contain the msgId key
300        """
301        try:
302            return json['data']['msgId']
303        except KeyError as err:
304            raise JsonMsgidMissingError(f'Object does not contain property {str(err)}') from err
305
306    @staticmethod
307    def mtype_str_from_json(json: dict) -> str:
308        """Return message type from Daemon API JSON response.
309
310        Args:
311            json (dict): JSON API response
312        Returns:
313            :obj:`str`: JSON API response message type string
314        Raises:
315            JsonMTypeMissingError: Raised if Daemon API response does not contain the mType key
316        """
317        try:
318            return json['mType']
319        except KeyError as err:
320            raise JsonMTypeMissingError(f'Object does not contain property {str(err)}') from err
321
322    @staticmethod
323    def nadr_from_json(json: dict) -> int:
324        """Return response nadr from Daemon API JSON response.
325
326        Args:
327            json (dict): JSON API response
328        Returns:
329            :obj:`int`: JSON API response device address
330        Raises:
331            JsonNadrMissingError: Raised if Daemon API response does not contain the nAdr key
332        """
333        try:
334            return json['data']['rsp']['nAdr']
335        except KeyError as err:
336            raise JsonNadrMissingError(f'Object does not contain property {str(err)}') from err
337
338    @staticmethod
339    def pnum_from_json(json: dict) -> int:
340        """Return response pnum from Daemon API JSON response.
341
342        Args:
343            json (dict): JSON API response
344        Returns:
345            :obj:`int`: JSON API response peripheral number
346        Raises:
347            JsonNadrMissingError: Raised if Daemon API response does not contain the pnum key
348        """
349        try:
350            return json['data']['rsp']['pnum']
351        except KeyError as err:
352            raise JsonNadrMissingError(f'Object does not contain property {str(err)}') from err
353
354    @staticmethod
355    def pcmd_from_json(json: dict) -> int:
356        """Return response pcmd from Daemon API JSON response.
357
358        Args:
359            json (dict): JSON API response
360        Returns:
361            :obj:`int`: JSON API response peripheral command
362        Raises:
363            JsonNadrMissingError: Raised if Daemon API response does not contain the pcmd key
364        """
365        try:
366            return json['data']['rsp']['pcmd']
367        except KeyError as err:
368            raise JsonNadrMissingError(f'Object does not contain property {str(err)}') from err
369
370    @staticmethod
371    def hwpid_from_json(json: dict) -> int:
372        """Return response hwpid from Daemon API JSON response.
373
374        Args:
375            json (dict): JSON API response
376        Returns:
377            :obj:`int`: JSON API response hardware profile ID
378        Raises:
379            JsonHwpidMissingError: Raised if Daemon API response does not contain the hwpId key
380        """
381        try:
382            return json['data']['rsp']['hwpId']
383        except KeyError as err:
384            raise JsonHwpidMissingError(f'Object does not contain property {str(err)}') from err
385
386    @staticmethod
387    def rcode_from_json(json: dict) -> int:
388        """Return response rcode from Daemon API JSON response.
389
390        Args:
391            json (dict): JSON API response
392        Returns:
393            :obj:`int`: JSON API response DPA rcode
394        Raises:
395            JsonRCodeMissingError: Raised if Daemon API response does not contain the rcode key
396        """
397        try:
398            return json['data']['rsp']['rCode']
399        except KeyError as err:
400            raise JsonRCodeMissingError(f'Object does not contain property {str(err)}') from err
401
402    @staticmethod
403    def dpa_value_from_json(json: dict) -> int:
404        """Return response DPA value from Daemon API JSON response.
405
406        Args:
407            json (dict): JSON API response
408        Returns:
409            :obj:`int`: JSON API response dpa value
410        Raises:
411            JsonDpaValueMissingError: Raised if Daemon API response does not contain the dpaVal key
412        """
413        try:
414            return json['data']['rsp']['dpaVal']
415        except KeyError as err:
416            raise JsonDpaValueMissingError(f'Object does not contain property {str(err)}') from err
417
418    @staticmethod
419    def pdata_from_json(json: dict) -> Union[List[int], None]:
420        """Return pdata from Daemon API JSON response if available.
421
422        Args:
423            json (dict): JSON API response
424        Returns:
425            :obj:`Union[List[int], None]`: JSON API response pdata or None if there are no PDATA
426        """
427        pdata = None
428        try:
429            raw = json['data']['raw']
430            response = None
431            if isinstance(raw, list):
432                response = raw[0]['response']
433            elif isinstance(raw, dict):
434                response = raw['response']
435            response = response.split('.')
436            if len(response) > 8:
437                pdata = [int(x, 16) for x in response[8:]]
438        except KeyError:
439            pdata = None
440        finally:
441            return pdata
442
443    @staticmethod
444    def result_from_json(json: dict) -> dict:
445        """Return response result from Daemon API JSON response.
446
447        Args:
448            json (dict): JSON API response
449        Returns:
450            :obj:`dict`: JSON API response result object
451        Raises:
452            JsonResultMissingError: Raised if JSON API response does not contain the result key
453        """
454        try:
455            return json['data']['rsp']['result']
456        except KeyError as err:
457            raise JsonResultMissingError(f'Object does not contain property {str(err)}') from err
458
459    @staticmethod
460    def status_from_json(json: dict) -> int:
461        """Return response status from Daemon API JSON response.
462
463        Args:
464            json (dict): JSON API response
465        Returns:
466            :obj:`int`: JSON API response status code
467        Raises:
468            JsonStatusMissingError: Raised if JSON API response does not contain the status key
469        """
470        try:
471            return json['data']['status']
472        except KeyError as err:
473            raise JsonStatusMissingError(f'Object does not contain property {str(err)}') from err
474
475    @staticmethod
476    def generic_rdata_from_json(json: dict) -> str:
477        """Return generic response data from Daemon API JSON response.
478
479        Args:
480            json (dict): JSON API response
481        Returns:
482            :obj:`int`: JSON API response status code
483        Raises:
484            JsonStatusMissingError: Raised if JSON API response does not contain path to rData.
485        """
486        try:
487            return json['data']['rsp']['rData']
488        except KeyError as err:
489            raise JsonGenericDataMissingError(f'Object does not contain property {str(err)}') from err
490
491    @staticmethod
492    def parse_json_into_members(json: dict, omit_result: bool = False):
493        """Parse JSON response into response members.
494
495        Args:
496            json (dict): JSON API response
497            omit_result (bool): Do not parse result
498        Returns:
499            :obj:`(str, int, int, int, int, List[int], dict)`: Response members
500        """
501        msgid = Common.msgid_from_json(json=json)
502        nadr = Common.nadr_from_json(json=json)
503        hwpid = Common.hwpid_from_json(json=json)
504        rcode = Common.rcode_from_json(json=json)
505        dpa_value = Common.dpa_value_from_json(json=json)
506        pdata = Common.pdata_from_json(json=json)
507        if omit_result:
508            result = None
509        else:
510            result = Common.result_from_json(json=json) if rcode == dpa_constants.ResponseCodes.OK else None
511        return msgid, nadr, hwpid, rcode, dpa_value, pdata, result
512
513    @staticmethod
514    def string_to_mtype(string: str) -> MessageType:
515        """Convert message type string to message type enum member value.
516
517        Args:
518            string (str): Message type string
519        Returns:
520            :obj:`MessageType`: Message type enum member
521        Raises:
522            UnsupportedMessageTypeError: Raised if message type is not recognized as a member of any message type enum
523        """
524        messages = [GenericMessages, ExplorationMessages, CoordinatorMessages, NodeMessages, OSMessages, EEPROMMessages,
525                    EEEPROMMessages, RAMMessages, LEDRMessages, LEDGMessages, IOMessages, ThermometerMessages,
526                    UartMessages, FrcMessages, DALIMessages, BinaryOutputMessages, SensorMessages, LightMessages]
527        for item in messages:
528            if string in item:
529                return item(string)
530        raise UnsupportedMessageTypeError(f'Unknown or unsupported message type: {string}.')
531
532    # general
533
534    @staticmethod
535    def bitmap_to_nodes(bitmap: List[int], coordinator_shift: bool = False) -> List[int]:
536        """Convert node bitmap to list of nodes.
537
538        Args:
539            bitmap (List[int]): Node bitmap represented by list of integers
540            coordinator_shift (bool): Bitmap contains dummy coordinator value
541        Returns:
542            :obj:`list` of :obj:`int`: List of node addresses from bitmap
543        """
544        nodes = []
545        start = 0 if not coordinator_shift else 1
546        for i in range(start, len(bitmap * 8)):
547            if bitmap[int(i / 8)] & (1 << (i % 8)):
548                nodes.append(i)
549        return nodes
550
551    @staticmethod
552    def nodes_to_bitmap(nodes: List[int]) -> List[int]:
553        """Convert list of nodes to node bitmap.
554
555        Args:
556            nodes (List[int]): List of node addresses
557        Returns:
558            :obj:`list` of :obj:`int`: Nodes bitmap represented by list of 30 integers
559        """
560        bitmap = [0] * 30
561        for node in nodes:
562            bitmap[math.floor(node / 8)] |= (1 << (node % 8))
563        return bitmap
564
565    @staticmethod
566    def bitmap_4byte_to_indexes(bitmap: List[int]) -> List[int]:
567        """Convert 4 byte bitmap to list of indexes.
568
569        Args:
570            bitmap (List[int]): Index bitmap.
571
572        Returns:
573            :obj:`List` of :obj:`int`: List of indexes.
574        """
575        indexes = [0] * 32
576        for i in range(0, len(bitmap * 8)):
577            if bitmap[int(i / 8)] & (1 << (i % 8)):
578                indexes[i] = 1
579        return indexes
580
581    @staticmethod
582    def indexes_to_4byte_bitmap(values: List[int]) -> List[int]:
583        """Convert list of indexes to a 4 byte bitmap.
584
585        Args:
586            values (List[int]): List of indexes
587        Returns:
588            :obj:`list` of :obj:`int`: Index bitmap represented by list of 4 integers
589        """
590        bitmap = [0] * 4
591        for value in values:
592            bitmap[math.floor(value / 8)] |= (1 << (value % 8))
593        return bitmap
594
595    @staticmethod
596    def is_hex_string(string: str) -> bool:
597        """Check if string contains only hexadecimal characters.
598
599        Args:
600            string (str): Input string
601        Returns:
602            :obj:`bool`: True if string contains only hexadecimal characters, False otherwise
603        """
604        if len(string) == 0:
605            return False
606        return not set(string) - set('0123456789abcdefABCDEF')
607
608    @staticmethod
609    def hex_string_to_list(string: str) -> List[int]:
610        """Convert hexadecimal string to list of unsigned integers.
611
612        Args:
613            string (str): Hexadecimal string
614        Returns:
615            :obj:`list` of :obj:`int`: List of integers from hexadecimal string
616        Raises:
617            ValueError: Raised if string is of uneven length or contains non-hexadecimal characters
618        """
619        if not len(string) % 2 == 0:
620            raise ValueError('Argument should be even length.')
621        if not Common.is_hex_string(string):
622            raise ValueError('Argument is not a hexadecimal string.')
623        return [int(string[i:i + 2], base=16) for i in range(0, len(string), 2)]
624
625    @staticmethod
626    def list_to_hex_string(values: List[int], separator: str = ' ', uppercase: bool = True) -> str:
627        """Convert list of unsigned integers to hexadecimal string.
628
629        Args:
630            values (List[int]): List of unsigned integers
631            separator (str, optional): Separator for byte string. Defaults to empty string.
632            uppercase (bool, optional): Output hex string uppercase. Defaults to False.
633
634        Returns:
635            :obj:`string`: Hexadecimal string representation of the list
636        """
637        hex_format = 'X' if uppercase else 'x'
638        return separator.join(f'{value:02{hex_format}}' for value in values)
639
640    @staticmethod
641    def peripheral_list_to_bitmap(values: List[int]) -> List[int]:
642        """Convert list of peripheral numbers into a bitmap of peripherals.
643
644        For example, the coordinator peripheral would be represented by the 1st bit in bitmap.
645
646        Args:
647            values (List[int]): List of peripheral numbers
648        Returns:
649            :obj:`list` of :obj:`int`: Peripheral bitmap represented by list of 4 integers
650        """
651        bitmap = [0 for _ in range(32)]
652        for value in values:
653            bitmap[value] = 1
654        byte_list = []
655        for bits in [bitmap[i:i + 8] for i in range(0, len(bitmap), 8)]:
656            bits.reverse()
657            byte = 0
658            for bit in bits:
659                byte = (byte << 1) | bit
660            byte_list.append(byte)
661        return byte_list
662
663    @staticmethod
664    def values_in_byte_range(values: List[int]) -> bool:
665        """Check if list elements are within unsigned integer byte range.
666
667        Args:
668            values (List[int]): Input data
669        Returns:
670            :obj:`bool`: True if values are in range, False otherwise
671        """
672        return len([value for value in values if value < 0 or value > 255]) == 0
673
674    @staticmethod
675    def byte_complement(value: int):
676        """Convert unsigned 1B value into a signed 1B value.
677
678        Args:
679            value (int): Input unsigned 1B value
680        Returns:
681            :obj:`int`: Signed 1B value
682        Raises:
683            ValueError: Raised when value is not in unsigned 8bit range.
684        """
685        if not 0 <= value <= 0xFF:
686            raise ValueError('Not an unsigned 1B value.')
687        if value < 0x80:
688            return value
689        return value - 0x100
690
691    @staticmethod
692    def word_complement(value: int) -> int:
693        """Convert unsigned 2B value into a signed 2B value.
694
695        Args:
696            value (int): Input unsigned 2B value
697        Returns:
698            :obj:`int`: Signed 2B value
699        Raises:
700            ValueError: Raised when value is not in unsigned 16bit range.
701        """
702        if not 0 <= value <= 0xFFFF:
703            raise ValueError('Not an unsigned 2B value.')
704        if value < 0x8000:
705            return value
706        return value - 0x10000
707
708    @staticmethod
709    def bcd_to_decimal(byte: int) -> int:
710        """Convert a Binary-Coded Decimal (BCD) value to decimal integer.
711
712        Args:
713            byte (int): BCD value to convert.
714
715        Returns:
716            :obj:`int`: Decimal value encoded in BCD.
717
718        Raises:
719            ValueError: Raised when byte argument is not a valid BCD value.
720
721        Examples:
722            >>> Common.bcd_to_decimal(0x42)
723            42
724        """
725        high = (byte >> 4) & 0x0F
726        low = byte & 0x0F
727        if high > 9 or low > 9:
728            raise ValueError('Not a BCD value.')
729        return high * 10 + low
730
731    @staticmethod
732    def dpa_build_date_to_str(par1: int, par2: int) -> str:
733        """Convert DPA build date in BCD format to human-readable string.
734
735        Outputs date string in the following format: DD.MM.YYYY.
736
737        Args:
738            par1 (int): BCD-encoded day of DPA build date.
739            par2 (int): BCD-encoded month and year of DPA build date.
740
741        Returns:
742            str: Human-readable DPA build date string.
743        """
744        try:
745            day = Common.bcd_to_decimal(par1)
746            month = par2 & 0x0F
747            year = 2010 + ((par2 >> 4) & 0x0F)
748            return f'{day}.{month}.{year}'
749        except ValueError as e:
750            raise ValueError(f'Failed to convert DPA build date to string: {str(e)}') from e
751
752    @staticmethod
753    def dpa_version_to_str(dpa_version: int) -> str:
754        """Convert DPA version in BCD format to human-readable version string.
755
756        Args:
757            dpa_version (int): DPA version encoded in BCD format.
758
759        Returns:
760            str: Human-readable DPA version string.
761
762        Raises:
763            ValueError: Raised when dpa_version is not a valid BCD value.
764        """
765        try:
766            major = Common.bcd_to_decimal(int(dpa_version / 256))
767            minor = dpa_version & 0x00FF
768            return f'{major}.{minor:02X}'
769        except ValueError as e:
770            raise ValueError(f'Failed to convert version to string: {str(e)}') from e
771
772    @staticmethod
773    def fletcher_checksum(init: int, data: List[int]) -> int:
774        """Calculate one's complement Fletcher checksum from list of bytes.
775
776        See https://doc.iqrf.org/DpaTechGuide/pages/FletcherCSharp.html
777
778        Args:
779            init (int): Initial value.
780            data (List[int]): List of bytes to calculate checksum from.
781
782        Returns:
783            :obj:`int`: 16bit Fletcher checksum integer value.
784        """
785        checksum = init
786        for byte in data:
787            low = checksum & 0xFF
788            low += byte
789            if (low & 0x100) != 0:
790                low += 1
791            high = checksum >> 8
792            high += low & 0xFF
793            if (high & 0x100) != 0:
794                high += 1
795            checksum = (low & 0xFF) | (high & 0xFF) << 8
796        return checksum