Module udp 

The Semtech packet forwarder protocol, both sides.

A gateway and a network server exchange six kinds of UDP datagram, described by PROTOCOL.TXT in Semtech’s packet_forwarder. Each begins with the same three bytes, a protocol version of 2 and a random token, then an identifier that says which kind it is:

• The gateway sends PUSH_DATA with the packets it heard, and the server answers PUSH_ACK with the same token.
• The gateway sends PULL_DATA to hold a route open through whatever network address translation sits in front of it, and the server answers PULL_ACK.
• The server sends PULL_RESP with a packet to transmit, and the gateway answers TX_ACK saying whether it accepted it.

The protocol has no authentication and no retries, which is why it belongs on a private network or behind a tunnel. Packet builds and parses every kind, and the objects they carry are in Rxpk, Stat, Txpk, and TxStatus.

Examples

A server reads what a gateway sent and answers it: a PUSH_DATA with a packet it heard, then a PULL_DATA holding its route open for downlinks.

use pamoja_gateway::udp::{Eui, Packet, PacketKind, Rxpk, Uplink};
use pamoja_lora::LinkSettings;

let gateway = Eui::from_hex("b827ebfffe010203").expect("sixteen hex digits");
let heard = Rxpk::new(868_100_000, LinkSettings::new(9, 125_000), b"open".to_vec());
let arrivals = [
    Packet::PushData { token: 1, gateway, uplink: Uplink::from(heard) }.to_bytes(),
    Packet::PullData { token: 2, gateway }.to_bytes(),
];

for datagram in arrivals {
    let packet = Packet::parse(&datagram)?;
    assert_eq!(packet.gateway(), Some(gateway));
    let ack = packet.acknowledgment().expect("both are acknowledged");
    assert_eq!(ack.token(), packet.token());
    match packet.kind() {
        PacketKind::PushData => assert_eq!(ack.kind(), PacketKind::PushAck),
        PacketKind::PullData => assert_eq!(ack.kind(), PacketKind::PullAck),
        other => unreachable!("a gateway does not send {other:?} here"),
    }
}

Structs

Eui

A gateway’s unique identifier, the eight bytes it puts in every datagram it sends.

Rxpk

A packet the gateway heard, with the metadata the protocol carries beside it.

Stat

The gateway’s own status report.

Txpk

A packet the server asks the gateway to transmit.

Uplink

What a PUSH_DATA carries: the packets heard, and the gateway’s own report.

Enums

CrcStatus

What the CRC of a received packet said.

Modulation

How a packet was modulated.

Packet

One datagram of the protocol.

PacketKind

Which kind of datagram, as its fourth byte says.

ProtocolError

Why a datagram is not one this protocol defines.

TxStatus

What became of a downlink the server asked for.

Constants

DEFAULT_PORT

The UDP port a packet forwarder sends to by convention, which the protocol itself does not fix.

EUI_LEN

The length of a gateway’s unique identifier.

HEADER_LEN

The bytes before a datagram’s payload: the version, the token, and the identifier.

PROTOCOL_VERSION

The protocol version every datagram starts with.