Node

The Node is the building block of an OpenLCB/LCC network. Each Node can communicate with any other Node on the network by sending events or datagrams over the common bus. Each Node object can be attached to an Interface (or multiple) to allow for complex network architectures. Each Message should originate from one Node.

class pyolcb.Node(address: Address, interfaces: Interface | list[Interface], snip: SimpleNodeInfo = None, protocols: Protocol = None, allocate_alias: bool = True)

Implementation of an OpenLCB/LCC Node.

On an interface that is connected, the node claims an alias (Check ID, 200 ms listen, Reserve ID, Alias Map Definition) and announces itself with Initialization Complete before the constructor returns. On a GridConnect interface that connects later, or reconnects, it claims a fresh alias each time the link comes up.

Once permitted, the node answers Verify Node ID, Alias Mapping Enquiry, Protocol Support Inquiry, Simple Node Information requests (when snip is given) and Identify Events, and rejects addressed requests it does not implement. It also acts as a client: simple_node_info(), protocol_support_inquiry() and datagram_exchange() send a request and wait for the answer, and pyolcb.memory_config.MemoryConfiguration builds on them.

Parameters:

address (Address) – The address (full and optionally a preferred alias) to be associated with the Node.
interfaces (Interface | list[Interface]) – An Interface or list thereof to connect the Node to.
snip (SimpleNodeInfo, optional) – Identity strings to answer SNIP requests with.
protocols (protocols.Protocol, optional) – Protocols to report in Protocol Support Reply.
allocate_alias (bool) – Claim the alias with the standard handshake (default). False keeps the old behaviour of announcing with a preset alias immediately.

add_consumed_event(event_id: int, state: EventState = EventState.UNKNOWN): Declare an event this node consumes, so Identify Events and Identify Consumer are answered.

add_consumer(event: Event | int, function: callable)

Register a function to be run on receipt of a specific Event.

Parameters:

event (int | Event) – The ID or Event to consume. By default, if an int is provided for this parameter, and the (unsigned) value fits within two bytes, the Event will be tagged with the address of the Node. This behavior can be overridden by passing an Event object with no source address.
function (callable) – The function to be called upon receipt of the specified Event. Must be able to take no parameters.

add_frame_listener(function: callable): Call function(frame, outgoing) for every frame received (outgoing False) and every frame this node sends (True). Useful for traffic monitors.

add_produced_event(event_id: int, state: EventState = EventState.UNKNOWN): Declare an event this node produces, so Identify Events and Identify Producer are answered.

add_state_listener(function: callable): Call function(True) each time the node becomes permitted (after every successful alias claim) and function(False) when every interface has lost its connection.

addressed_request(destination: int, mti: int, payload: bytes, reply_mti: int, timeout: float = 2.0) → bytes

Send an addressed message to destination (an alias) and return the reassembled payload of the reply_mti message it answers with.

Raises InteractionRejected if the node rejects the request and ReplyTimeout if it does not answer.

alias_of(node_id: int) → int | None: The alias last seen for node_id, or None.

claim_alias(attempts: int = 16) → int: Claim an alias with the CID/RID/AMD handshake and announce the node. Blocks for at least 200 ms. Returns the alias.

consume(event: Event | int)

Run the consumer for a specific Event.

Parameters:: event (int | Event) – The ID or Event to consume. By default, if an int is provided for this parameter, and the (unsigned) value fits within two bytes, the Event will be tagged with the address of the Node. This behavior can be overridden by passing an Event object with no source address.
Returns:: Returns what the registered consumer function returns.
Return type:: any

datagram_exchange(destination: Address | int, data: bytes, timeout: float = 3.0, expect_reply: bool = True, reply_filter: callable = None, retries: int = 3) → bytes | None

Send a datagram and wait for it to be acknowledged, then (with expect_reply) for the reply datagram, which is acknowledged with Datagram Received OK.

Parameters:

destination (Address | int) – The node, as an Address or 48-bit node ID.
data (bytes) – The datagram content, 1 to 72 bytes.
timeout (float) – Seconds to wait for each answer. A Datagram Received OK that announces a longer reply time extends it.
expect_reply (bool) – Wait for a reply datagram after the acknowledgement.
reply_filter (callable, optional) – reply_filter(data) -> bool picks the reply among datagrams from the destination.
retries (int) – How often to resend after a temporary rejection.

Returns:

The reply datagram, b"" when no reply was wanted, or None if the node acknowledged without announcing a reply.

Return type:

bytes | None

get_alias() → int

Get the Node’s alias.

Returns:: Returns the Node’s alias as an int.
Return type:: int

get_consumer(event: Event | int)

Get the consumer for a specific Event.

Parameters:: event (int | Event) – The ID or Event to consume. By default, if an int is provided for this parameter, and the (unsigned) value fits within two bytes, the Event will be tagged with the address of the Node. This behavior can be overridden by passing an Event object with no source address.
Returns:: Returns the registered consumer function.
Return type:: callable

identify_consumer(event_id: int): Ask the consumers of event_id to identify themselves and their state.

identify_events(destination: int = None): Ask one node (by alias) or, with no destination, every node to identify its events.

identify_producer(event_id: int): Ask the producers of event_id to identify themselves and their state.

node_id_of(alias: int) → int | None: The node ID last seen for alias, or None.

property permitted: bool: True once the node has claimed an alias and may send messages.

process_message(message): Handle one received frame (a Frame or can.Message). Interfaces call this for every frame they receive.

produce(event: int | Event)

Produce an Event and send the resulting message on all interfaces.

Parameters:: event (int | Event) – The ID or Event to produce and send. By default, if an int is provided for this parameter, and the (unsigned) value fits within two bytes, the Event will be tagged with the address of the Node. This behavior can be overridden by passing an Event object with no source address.

produce_event(event_id: int): Send a Producer/Consumer Event Report for the full 64-bit event_id.

protocol_support_inquiry(destination: Address | int, timeout: float = 2.0) → Protocol: Ask a node which protocols it supports.

protocol_support_reply(destination: int): Send this node’s Protocol Support Reply to destination (an alias).

remove_consumer(event: Event | int)

Deregister the function to be run on receipt of a specific Event.

Parameters:: event (int | Event) – The ID or Event to consume. By default, if an int is provided for this parameter, and the (unsigned) value fits within two bytes, the Event will be tagged with the address of the Node. This behavior can be overridden by passing an Event object with no source address.

replace_consumer(event: Event | int, function: callable)

Replace a function that is run on receipt of a specific Event.

Parameters:

event (int | Event) – The ID or Event to consume. By default, if an int is provided for this parameter, and the (unsigned) value fits within two bytes, the Event will be tagged with the address of the Node. This behavior can be overridden by passing an Event object with no source address.
function (callable) – The function to be called upon receipt of the specified Event. Must be able to take no parameters.

resolve_alias(node: Address | int, timeout: float = 1.0) → int: Find the alias of a node given as an Address or a 48-bit node ID, asking the network with an Alias Mapping Enquiry if it is not yet known.

send(messages: Message | list[Message])

Send a Message (or sequence thereof) from this Node on all registered interfaces.

Parameters:: messages (Message | list[Message]) – The Message (or ordered list thereof) to send

send_addressed(mti: int, destination: int, payload: bytes = b''): Send an addressed message to destination (an alias), split into frames as needed.

send_datagram(destination: int, data: bytes): Send a datagram to destination (an alias) without waiting for the acknowledgement.

send_frame(frame: Frame | list[Frame]): Send one or more raw frames. Requires a claimed alias.

send_global(mti: int, payload: bytes = b''): Send a global message (12-bit mti) with up to 8 bytes of payload.

set_datagram_handler(datagram_handler: callable)

Register a function to be run on receipt of a Datagram.

Parameters:: datagram_handler (callable) – The function to be called upon receipt of a Datagram packet. Must take a Datagram as the first parameter. Return False to reject the datagram; anything else accepts it.

set_unknown_message_processor(function: callable)

Register a function to be run on receipt of a message of unknown type.

Parameters:: function (callable) – The function to be called upon receipt of an unknown message. Must take a Message as the first parameter.

simple_node_info(destination: Address | int, timeout: float = 3.0) → SimpleNodeInfo: Ask a node for its Simple Node Information (manufacturer, model, versions, user name).

verify_node_id(address: Address | int = None)

Send a request to verify aliases on an OpenLCB/LCC network.

Parameters:: address (Address | int = None) – If specified, only request a response for a Node with a given alias. Otherwise, request responses from each Node attached to all registered interfaces.

wait_permitted(timeout: float = None) → bool: Block until the node holds an alias. Returns False on timeout.