Dispatcher API Reference¶

This section documents the Dispatcher class and related functionality in pyMC_Core.

Dispatcher¶

pymc_core.node.dispatcher.Dispatcher ¶

Dispatcher(radio, *, tx_delay=0.05, log_fn=None, packet_filter=None)

Handles all the packet routing and radio communication.

This class doesn't do much packet processing itself - it just routes incoming packets to the right handler that knows what to do with them.

add_raw_packet_subscriber ¶

add_raw_packet_subscriber(callback)

Subscribe to every raw packet. Callback (pkt, data) or (pkt, data, analysis). Forward raw RX to clients to track repeats by packet hash.

add_raw_rx_subscriber ¶

add_raw_rx_subscriber(callback)

Subscribe to every incoming raw RX. Callback receives (data, rssi, snr). Called before duplicate/blacklist so clients get every repeat.

cleanup ¶

cleanup()

Clean up resources when shutting down.

clear_packet_filter ¶

clear_packet_filter()

Clear packet filter data.

expect_ack ¶

expect_ack(crc)

Register an ACK CRC we're waiting for and return an asyncio.Event that will be set as soon as the ACK arrives (or is already cached).

get_filter_stats ¶

get_filter_stats()

Get current packet filter statistics.

register_default_handlers ¶

register_default_handlers(*, contacts=None, local_identity=None, channel_db=None, event_service=None, node_name=None, radio_config=None)

Quick setup for all the standard packet handlers.

register_fallback_handler ¶

register_fallback_handler(handler)

Register a fallback handler for unhandled payload types.

register_handler ¶

register_handler(payload_type, handler_instance)

Register a handler for a specific type of packet.

remove_raw_packet_subscriber ¶

remove_raw_packet_subscriber(callback)

Unsubscribe from raw packet notifications (after parse).

remove_raw_rx_subscriber ¶

remove_raw_rx_subscriber(callback)

Unsubscribe from raw RX notifications.

run_forever `async` ¶

run_forever()

Run the dispatcher maintenance loop indefinitely (call this in an asyncio task).

send_packet `async` ¶

send_packet(packet, wait_for_ack=True, expected_crc=None)

Send a packet and optionally wait for an ACK. Uses a lock to serialize transmissions instead of dropping packets.

Parameters:

Name	Type	Description	Default
`packet`	`Packet`	The packet to send	required
`wait_for_ack`	`bool`	Whether to wait for an ACK	`True`
`expected_crc`	`Optional[int]`	The expected CRC for ACK matching. If None, will be calculated from packet.	`None`

set_ack_received_listener ¶

set_ack_received_listener(callback)

Set optional listener for ACK CRCs (e.g. companion send_confirmed).

set_contact_book ¶

set_contact_book(contact_book)

Set the contact book for decryption operations.

set_default_path_hash_mode ¶

set_default_path_hash_mode(mode)

Set or clear the default path hash mode for flood packets with 0 hops.

When set, packets sent via send_packet() that have not already had path hash mode applied (e.g. by the companion) will get path_len bits 6-7 set from this mode. Companion-originated packets are never overwritten.

Parameters:

Name	Type	Description	Default
`mode`	`Optional[int]`	0=1-byte, 1=2-byte, 2=3-byte per hop; None to disable.	required

set_raw_packet_callback ¶

set_raw_packet_callback(callback)

Set callback for raw packet data (includes both parsed packet and raw bytes).

wait_for_ack `async` ¶

wait_for_ack(crc, timeout=ACK_TIMEOUT)

Wait for a specific ACK CRC for up to timeout seconds.

Dispatcher Components¶

Packet Routing¶

The Dispatcher handles routing of packets to appropriate handlers based on packet type and content.

Handler Registration¶

# Register a handler for specific packet types
dispatcher.register_handler(PacketType.DATA, data_handler)
dispatcher.register_handler(PacketType.ACK, ack_handler)

Packet Transmission¶

# Send packets through the dispatcher
await dispatcher.send_packet(packet)

Key Methods¶

register_handler(packet_type, handler) - Register a handler for a packet type
unregister_handler(packet_type, handler) - Remove a handler registration
send_packet(packet) - Send a packet through the dispatcher
handle_packet(packet) - Process an incoming packet
get_registered_handlers() - Get list of registered handlers

Handler Interface¶

All packet handlers should implement the following interface:

class PacketHandler:
    async def handle_packet(self, packet: Packet) -> None:
        """Handle an incoming packet."""
        pass

Packet Flow¶

Incoming Packet → Dispatcher.receive_packet()
Handler Lookup → Find registered handler for packet type
Handler Execution → Call handler.handle_packet(packet)
Response Handling → Handle any response packets generated

Error Handling¶

The Dispatcher includes built-in error handling for: - Invalid packet types - Handler execution errors - Packet validation failures - Transmission timeouts

Thread Safety¶

The Dispatcher is designed to be thread-safe for concurrent packet handling and registration operations.