Skip to content

Latest commit

 

History

History
132 lines (110 loc) · 10.1 KB

README.md

File metadata and controls

132 lines (110 loc) · 10.1 KB
Raw

OK-DMR Lib

.github/workflows/sanity.yml Code Style: Python Black License Last released version PyPI downloads Python versions Wheel Codecov

This package provides way to parse and assemble various DMR ETSI protocols and functions, in pure Python implementation

Supported features

FEC (Forward Error Correction)

Algorithm Encoding Decoding / Verification
Hamming (7,4,3) ✅ ✅
Hamming (13,9,3) ✅ ✅
Hamming (15,11,3) ✅ ✅
Hamming (16,11,3) ✅ ✅
Hamming (17,12,3) ✅ ✅
Golay (20,8,7) ✅ ✅
Quadratic Residue (16,7,6) ✅ ✅
Reed-Solomon (12,9,4) ✅ ✅
Rate 3/4 Trellis ✅ ✅
Block Product Turbo Code (196,96) ✅ ✅
Variable length BPTC (BPTC 128,72) ✅ ✅
Variable length BPTC (BPTC 68,28) for CACH/Short LC ✅ ✅
Variable length BTPC (BPTC 32,11) for Single-Burst ✅ ✅

CRC (Cyclic Redundancy Check) and Checksums

Name Generate Verify
5-bit checksum ✅ ✅
CRC-8 (8-bit CRC) ✅ ✅
CRC-9 ✅ ✅
CRC-CCIT (CRC16-CCIT) ✅ ✅
CRC-32 (32-bit CRC) ✅ ✅

ETSI PDUs (Protocol Data Units)

Name Encoding / Decoding Description
CSBK ✅ Control Signalling Block, namely: BS Outbound Activation, Unit-Unit Request/Answer, Negative ACK, Preamble, Channel Timing
EMB ✅ Embedded Signalling
FULL LC ✅ Full Link Control, namely: Group Voice, Unit-Unit, Talker Alias (header + blocks1,2,3), GPSInfo, Terminator with LC
SHORT LC ✅ Short Link Control, namely: Activity, Null
SLOT ✅ Slot Type
SYNC ✅ Synchronization patterns
Data Header ✅ Confirmed/Unconfirmed, Response, Defined Short Data
PI Header ✅ Privacy (PI) Header, without further understanding of transported data
Rate 1 Data ✅ Rate 1 data (confirmed and unconfirmed) and last block data (confirmed and unconfirmed)
Rate 1/2 Data ✅ Rate 1/2 data (confirmed and unconfirmed) and last block data (confirmed and unconfirmed)
Rate 3/4 Data ✅ Rate 3/4 data (confirmed and unconfirmed) and last block data (confirmed and unconfirmed)
Full/Short Link Control ✅ FLC/SLC PDUs
UDP/IPv4 ✅ UDP/IPv4 compressed header/packet

ETSI Information Elements

All listed elements are supported as standalone enum/class representation, which allows for decoding/encoding and describing data (discovery):

Access Types (AT), CRC Mask, CSBKO (CSBK Opcode), DPF (Data Packet Format), DT (Data Type), FID (Feature Set ID), FLCO ( Full LC Opcode), LCSS (LC Start/Stop), PI (Pre-emption and power control indicator), SLCO (Short LC Opcode), SYNC ( Synchronization pattern), Activity ID, Additional Information Field, Answer/Response, CTO (Channel Timing Opcode), DI ( Dynamic Identifier), Position Error, Reason Code, Service Options, Talker Alias Data Format, Defined Data Format (DD), Selective Automatic Repeat reQuest (SARQ), Re-Synchronize Flag (S), Send sequence number (N(S)), SAP identifier (SAP), Supplementary Flag (SF), Unified Data Transport Format (UDT Format), UDP Port Identifier (SPID/DPID), IP Address Identifier (SAID/DAID)

Hytera

Protocol Name Encoding / Decoding
Hytera Simple Transport Reliability Protocol (HSTRP) ✅
Hytera Radio Network Protocol (HRNP) ✅
Hytera DMR Application Protocol (HDAP) ✅
Radio Registration Service (RRS) ✅
Location Protocol (LP) ✅
Radio Control Protocol (RCP) ✅
Text Message Protocol (TMP) ✅
  • Not all opcodes in all protocols are implemented, however it will fail with descriptive message, which opcode is missing in particular operation (decoding, description, encoding)

Motorola

Protocol Name Encoding / Decoding
Location Request Response Protocol (LRRP) ✅
Automatic Registration Service (ARS) ✅
Text Messaging Service (TMS) ✅
  • Motorola has MBXML (Motorola Binary XML) which is used to represent LRRP/ARRP documents, ok-dmrlib contains abstract MBXML implementation with various tools, LRRP implementation tested with both examples and real-world data
  • LRRP is supported as [bytes] <-> [mbxml document(s)] -> [xml representation], currently serialization of xml document to bytes is not supported
  • There are some catches, when you want to serialize MBXML token with common name, look through the test_mbxml and test_lrrp modules, to see how to select specific (correct) token programatically

Available CLI tools

  • dmrlib-pcap-tool - PCAP/PCAPNG traffic description and data extraction
  • dmrlib-dmr-burst - Describe full Tier-II burst (33 bytes)
  • dmrlib-dmr-header - Describe DMR Data Header
  • dmrlib-dmr-ipudp - Describe DMR UDP/IPv4 Compressed data (header + user payload)
  • dmrlib-hytera-hstrp - Hytera Simple Transport Protocol
  • dmrlib-hytera-hdap - Hytera DMR Application Protocol
  • dmrlib-hytera-hrnp - Hytera Radio Network Protocol
  • dmrlib-hytera-lp - Hytera Location Protocol
  • dmrlib-hytera-rcp - Hytera Radio Control Protocol
  • dmrlib-hytera-rrs - Hytera Radio Registration Service
  • dmrlib-hytera-tmp - Hytera Text Message Protocol

Additional notes

  • Almost every class/enum supports BitsInterface (de-serialization from on-air bits, serialization to transmission bits) , or for byte-aligned protocols (Hytera, Motorola) BytesInterface (with explicit endianness support)
  • Every FEC/CRC implemented supports both calculation, verification and (if possible) also self-correction
  • Working with Vocoder and Data/Control Bursts is supported, along with handling rates 1, 1/2 and 3/4
  • CRCs interface classes may require appropriate CRC Mask to be provided when generating or verifying
  • Through dmr-kaitai handling of ETSI, Hytera and MMDVM/Homebrew UDP data is supported
  • To inspect on-wire traffic PcapTool (provided in cli as dmrlib-pcap-tool script) supports PCAP/PCAPNG files with various functions on describing bursts, port/data filtering, data extraction, ...
  • Everything is tested, specifically now we have 95% pytest coverage for whole ok-dmrlib codebase
  • Not everything is probably documented as it should be, but the usage should always be very clear, when you look at tests of particular component