Skip to content
M17-ProjectPublic

About

Python M17 library.

Resources

Stars

1 star

Watchers

2 watching

Forks

Latest commit

 

History

186 Commits

Folders and files

Repository files navigation

pyM17

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.

Install

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.

Examples

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 event

A 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.

Modules

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

Testing

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.

Credits and license

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.

About

Python M17 library.

Resources

Stars

1 star

Watchers

2 watching

Forks

Releases

Packages

Used by

Contributors

Languages