The M17 digital radio protocol in Python: frames, error correction, packets, encryption, signatures and the reflector protocol. Pure Python with no required dependencies, and bit-exact with libm17, the reference C implementation.
pip install m17 # core
pip install "m17[crypto]" # + AES and ECDSA signatures (cryptography)
pip install "m17[dsp]" # + RRC filtering (numpy)
Python 3.10 or newer.
A text message as symbols (4FSK levels -3, -1, +1, +3, 4800 per second):
import m17
from m17.lsf import LSF, PACKET, DATA, can
lsf = LSF(dst="@ALL", src="N0CALL", type=PACKET | DATA | can(0))
symbols = m17.encode_packet(lsf, m17.sms("Hello M17"))Receiving: feed synchronized symbols (one per symbol), get decoded events:
rx = m17.Receiver()
for event in rx.feed(symbols):
if isinstance(event, m17.Packet):
print(event.text, event.crc_ok)An encrypted, signed voice stream (payloads are 16 bytes, two Codec 2 3200 frames):
import os, time
from m17 import crypto
from m17.lsf import STREAM, VOICE, ENCR_AES, AES_256, SIGNED, meta_nonce
payloads = [bytes(16)] * 25 # 1 second of voice
aes_key = os.urandom(32)
private, public = crypto.generate_key()
lsf = LSF(dst="@ALL", src="N0CALL", type=STREAM | VOICE | ENCR_AES | AES_256 | SIGNED,
meta=meta_nonce(int(time.time()), os.urandom(10)))
symbols = m17.encode_stream(lsf, payloads, key=aes_key, signing_key=private)
rx = m17.Receiver(key=aes_key, public_keys=[public]) # decrypts, yields a Signature eventA reflector, as in the M17 Internet Interface specification (mrefd, UDP port 17000):
from m17.reflector import ReflectorClient
with ReflectorClient("reflector.example.org", "N0CALL", "A") as ref:
ref.send_packet(lsf, m17.sms("Hello reflector"))
for item in ref.receive(timeout=60):
print(item)From the command line, with symbol files compatible with m17-packet-encode -f and
m17-packet-decode from M17_Implementations:
python -m m17 sms --src N0CALL --dst @ALL "Hello" -o msg.sym
python -m m17 decode msg.sym
To transmit or receive over the air, the symbols still need RRC filtering and an FM
modulator (m17.phy.modulate() gives the baseband), and received audio needs a matched
filter (m17.phy.matched_filter()) and symbol timing recovery.
| Module | Contents |
|---|---|
callsign |
base-40 address encoding, hash addresses, @ALL |
crc |
CRC-16 (polynomial 0x5935) |
lsf |
LSF, TYPE bits, LICH chunks, GNSS position, ECD and nonce META |
fec |
convolutional code, puncturing, soft Viterbi, Golay(24,12) with Chase-II |
phy |
symbols, syncwords, interleaver, randomizer, soft slicer, RRC filter |
frames |
LSF, stream, packet and BERT frames: encoding and decoding |
packet |
building, splitting and reassembling packets, SMS |
transmission |
whole stream and packet transmissions |
receiver |
syncword search, frame decoding, decryption, signature checks |
crypto |
AES-CTR, 8/16/24-bit scramblers, stream digest, ECDSA (secp256r1) |
reflector |
mrefd datagrams and a reflector client |
pip install -e ".[test]"
pytest
The tests compare pyM17 with reference values from the C implementations, generated by
tools/gen_vectors.c (libm17), tools/gen_packet_vectors.py (m17-packet-encode) and
tools/gen_crypto_vectors.c (gr-m17's AES, scrambler and micro-ecc). Their headers say how
to rebuild them. Decoding matches libm17 exactly, including the Viterbi metric of noisy frames.
pyM17 was started by Michael McGinty W2FBI and continued by Luke Stamm WE3DZ. Version 0.2 is a rewrite by the M17 Project (Wojciech Kaczmarski SP5WWP), ported from libm17 and gr-m17.
AGPL-3.0, see LICENSE.