Module ot

Help

Expand description

§OpenThread API Module

This module contains (mostly) type-safe versions of the OpenThread API, excluding the platform API.

§Type Safety

Full type safety for an API which wasn’t created for type safety is hard. There are some operations which feel like they should be fully safe but are ultimately marked as unsafe because it might be possible to abuse in some way that causes undefined behavior.

§Types

Each enum, struct, or object in the OpenThread C API is associated with a safe Rust equivalent. For example:

§Ownership

Some OpenThread API objects, like otsys::otInstance and otsys::otMessage have hidden implementations and explicit ownership transfer. That means we must have a notation which is capable of both “owned” instances and “borrowed” references.

The rust equivalent of passing around a pointer to one of thse objects would be to pass around a reference: otInstance* becomes a &ot::Instance. Owned instances are “boxed” into a ot::Box, so an owned otInstance* would become a ot::Box<ot::Instance>, or a OtInstanceBox for short. When the box goes out of scope, the appropriate OpenThread C finalization API is called.

§Singleton/Multiple OpenThread Instances

OpenThread can be compiled to either only support a singleton instance or to support multiple independent OpenThread instances.

Currently, this crate only supports a singleton OpenThread instance. Attempting to create more than one OpenThread instance at a time will result in a runtime panic.

§Traits

The OpenThread API is broken down into “modules” of functionality containing types and related methods. Similarly, this Rust interface breaks down functionality into traits. This allows parts of the OpenThread API to be substituted with mocked versions for unit testing.

§Callbacks

In most cases, you register a callback by passing a closure to the appropriate callback registration API.

§Platform Implementations

This crate doesn’t directly provide the platform implementations for OpenThread—that needs to come from either a separate library or the program which is using this crate.

Re-exports§

pub use message::Message;
pub use message::MessageBuffer;

Modules§

message: Module for all things related to OpenThread messages.

Structs§

ActiveScanResult: This structure holds information about a network beacon discovered during an active scan.
AddressOrigin: Type representing the origin of an address
BackboneRouterMulticastListenerInfo: Functional equivalent of otsys::otBackboneRouterMUlticastListenerInfo.
BadSystemTime: Error type for when a system time cannot be converted to a timestamp.
BorderRouterConfig: Functional equivalent of otsys::otBorderRouterConfig.
BorderRoutingCounters: This structure represents border routing counters.
BorderRoutingDhcp6PdStateChangedStream: Stream for getting state changed events.
BorderRoutingPrefixTableEntry: Represents an entry from the discovered prefix table. Functional equivalent of otsys::otBorderRoutingPrefixTableEntry.
Box: A box for owning pointers to opaque types vended from the OpenThread API.
ChangedFlags
ChannelMask: Type representing a set of radio channels.
ChannelOutOfRange: Error type for when a given channel index is out of range.
DnsTxtEntry: Functional equivalent of otsys::otDnsTxtEntry.
DnsTxtEntryIterator: Functional equivalent of otsys::otDnsTxtEntryIterator.
DnssdCounters: This structure represents DNS-SD server counters.
DnssdQuery: Functional equivalent of otDnssdQuery
DnssdQueryIterator: Iterator type for DNS-SD Queries
EnergyScanResult: This structure holds information about energy levels detected on a channel.
ExtAddress: Data type representing a EUI64 address. Functional equivalent of otsys::otExtAddress.
ExtendedPanId: Data type representing an extended PAN-ID. Functional equivalent of otsys::otExtendedPanId.
ExternalRouteConfig: Data type representing an external route configuration. Functional equivalent of otsys::otExternalRouteConfig.
Instance: OpenThread instance.
Ip4Cidr: Data type representing an IPv4 CIDR.
Ip6AddressInfo: Data type representing IPv6 address information.
Ip6NetworkPrefix: Data type representing a 64-bit IPv6 network prefix.
Ip6Prefix: IPv6 subnet prefix with an arbitrary prefix length. Functional equivalent of otsys::otIp6Prefix.
IpCounters: This structure represents the IP layer counters.
LeaderData: This structure represents the Thread Leader Data.
LinkMetricsValues: Represents the result (value) for a Link Metrics query.
LinkModeConfig: Link Mode Config. Functional equivalent of otsys::otLinkModeConfig.
LocalExternalRouteIterator: Iterator type for external routes.
LocalOnMeshPrefixIterator: Iterator type for on-mesh prefixes.
MacCounters: This structure represents the MAC layer counters.
MalformedOrNoBufs: Error type for when an IPv6 header is malformed or there are no buffers to allocate.
MeshcopTlvIterator: An iterator type for parsing OpenThread TLV data.
MulticastListenerIterator: Iterator type for multicast listeners.
Nat64AddressMapping: NAT64 Address Mapping, which is part of NAT64 telemetry
Nat64AddressMappingIterator: NAT64 Address Mapping iterator
Nat64Counters: Represents the counters for NAT64
Nat64ErrorCounters: Represents the error counters for NAT64
Nat64ProtocolCounters: Counters for sum of all protocols for NAT64
NeighborInfo: This structure holds diagnostic information for a neighboring Thread node.
NeighborInfoIterator: Iterator type for neighbor info
NetifAddress: Data type representing IPv6 address from a network interface. Functional equivalent of otsys::otNetifAddress.
NetifAddressIterator: Iterates over the NetifAddress structs from Ip6::ip6_get_unicast_addresses().
NetworkKey: Network Key. Functional equivalent of otsys::otNetworkKey.
NetworkName: Network Name. Functional equivalent of otsys::otNetworkName.
NoBufs: Error type for when there are no buffers to allocate.
NullPlatform: Platform instance which does nothing.
OperationalDataset: Functional equivalent of otsys::otOperationalDataset.
OperationalDatasetTlvs: Functional equivalent of otsys::otOperationalDatasetTlvs.
PacketsAndBytes: This structure represents counters for packets and bytes.
ParseError: Error type for when there is some sort of parsing error.
PdProcessedRaInfo: This structure represents border routing counters.
PlatDnsUpstreamQuery: This structure represents the DNS Upstream Query context.
PlatTrelPeerInfo: Functional equivalent of otsys::otPlatTrelPeerInfo.
Pskc: PSKC. Functional equivalent of otsys::otPskc.
RadioCoexMetrics: This structure represents radio coexistence metrics.
RadioRegion: Represents a radio regulatory region/domain.
RouterInfo: Functional equivalent of otsys::otRouterInfo.
Scope: Type representing an IPv6 scope, as represented on IPv6 multicast addresses.
SecurityPolicy: Functional equivalent of otsys::otSecurityPolicy.
SockAddr: Functional equivalent of otsys::otSockAddr.
SrpServerHost: This opaque type (only used by reference) represents a SRP host.
SrpServerHostIterator: Iterates over the available SRP server hosts. See [SrpServer::srp_server_get_hosts].
SrpServerLeaseInfo: This structure represents the SRP Server Lease Info.
SrpServerResponseCounters: This structure represents SRP server response counters.
SrpServerService: This opaque type (only used by reference) represents a SRP service.
SrpServerServiceIterator: Iterates over all the available SRP services.
SrpServerServiceSubtypeIterator: Iterates over all the available SRP services subtypes.
SrpServerServiceUpdateId: The ID of a SRP service update transaction on the SRP Server.
StateChangedStream: Stream for getting state changed events.
TaskletsStream: Provides an asynchronous interface to ot::Tasklets.
Timestamp: Type representing a Thread timestamp.
TrelCounters: This structure represents the Thread TREL counters.
UdpSocket: Functional equivalent of otsys::otUdpSocket.
UdpSocketIterator: Iterates over the available UDP sockets. See Udp::udp_get_sockets.
UpstreamDnsCounters: Represents the count of queries, responses, failures handled by upstream DNS server
WrongSize: Error type for when a slice is not the correct size.

Enums§

BackboneRouterMulticastListenerEvent: Represents a Thread device role.
BorderAgentState: Represents the thread joiner state.
BorderRoutingDhcp6PdState: This enumeration represents the state of DHCPv6 Prefix Delegation State.
DeviceRole: Represents a Thread device role.
DnssdQueryType: Represents the type of a DNS query
Error: Error type for OpenThread calls. Functional equivalent of otsys::otError.
Icmp6EchoMode: Functional equivalent of otsys::otIcmp6EchoMode.
JoinerState: Represents the thread joiner state.
LogLevel: Logging Level. Functional equivalent of otsys::otLogLevel.
LogRegion: Logging Region. Functional equivalent of otsys::otLogRegion.
MeshcopTlv: Represents a type-length-value (TLV) item.
Nat64State: Represents a NAT64 Translator State.
NetifIdentifier: This enumeration defines the OpenThread network interface identifiers.
RoutePreference: Route Preference, as defined in RFC4191 Section 2.1.
SrpServerAddressMode: Represents the SRP server address mode.
SrpServerState: Represents the SRP server state.
ThreadVersion: Represents the thread version

Constants§

DECIBELS_UNSPECIFIED: Unspecified power
IP6_PREFIX_BITSIZE: Functional equivalent of otsys::OT_IP6_PREFIX_BITSIZE.
MAX_CHILD_ID: The largest child ID supported by OpenThread, 511.
MAX_NET_DATA_LEN: The maximum length of Thread network data, in bytes.
MAX_NUM_CHANNELS: The maximum number of individual channels that can be referenced by this API.
NETIF_INDEX_UNSPECIFIED: Unspecified network index.
ROUTER_ID_OFFSET: The bit offset to the router ID in an RLOC16.
TREL_DNSSD_SERVICE_NAME: DNS-SD Service Name for TREL
TREL_DNSSD_SERVICE_NAME_WITH_DOT: DNS-SD Service Name for TREL, with a dot at the end.

Traits§

BackboneRouter: Methods from the OpenThread “Backbone Router” Module. Currently only multicast routing related methods are added.
BorderAgent: Methods from the OpenThread “Border Agent” Module.
BorderRouter: Methods from the OpenThread “Border Router” Module.
Boxable: Trait for OpenThread Rust types for which an owned opaque instance is kept in a [ot::Box<>].
Cli: Methods from the OpenThread “CLI” Module.
Dataset: Methods from the OpenThread “OperationalDataset” Module.
DnsUpstream: DnsUpstream callback from platform to OT
Dnssd: Methods from the OpenThread DNS-SD Server Module.
DnssdExt: Extension trait for the trait Dnssd.
InfraInterface: Methods from the “Platform Infrastructure Interface” group [1]
InstanceInterface: Trait implemented by all OpenThread instances.
IntoOtError: Trait for converting types into otError values.
Ip6: Methods from the OpenThread “IPv6” Module.
Joiner: Methods from the OpenThread “Joiner” Module.
Link: Methods from the OpenThread “Link” Module.
LinkMetrics: Methods from the “Link Metrics “ group [1]
Nat64: Methods from the OpenThread “NAT64” Module.
NetData: Methods from the OpenThread “NetData” Module.
OtCastable: Trait used to indicate that the implementing type can be efficiently converted into a reference to the original OpenThread type identified by Self::OtType.
PlatTrel: Platform methods from the OpenThread TREL Module.
Platform: Trait for OpenThread platform implementations.
ProcessPollAsync: Trait that provides the [process_poll()] method.
Radio: Methods from the OpenThread “Radio” Module.
Reset: Reset-related methods from the OpenThread “Instance” Module.
SrpServer: Server Methods from the OpenThread SRP Module.
State: State-change-related methods from the OpenThread “Instance” Module.
Tasklets: Methods from the OpenThread “Tasklets” Module.
TaskletsStreamExt: Trait used to wrap around a mutex that polls internally without needing to externally unlock the mutex.
Thread: Methods from the OpenThread “Thread General” Module.
TlvIteratorExt: Extension trait for adding tlvs() method to &[u8].
Transparent: Trait used to indicate that the implementing type can be used by value and converted to/from the associated OpenThread type by value.
Trel: Methods from the OpenThread TREL Module.
Udp: Methods from the OpenThread “UDP” Module.
Uptime: Uptime-related methods from the OpenThread “Instance” Module.

Functions§

dns_txt_flatten: Converts a iterator of strings into a single string separated with [DNSSD_TXT_SEPARATOR_STR].
get_logging_level: Get the logging level.
get_thread_version: Returns the version of the Thread specification that OpenThread is configured to use. This is the safe equivalent of otsys::otThreadGetVersion().
get_thread_version_str: Returns a 'static-scoped string slice describing the version of the Thread specification that is currently in use.
get_version_string: Returns the OpenThread version string. This is the safe equivalent of otsys::otGetVersionString().
parse_label_from_subtype_service_name: Functional equivalent of otsys::otSrpServerParseSubTypeServiceName.
rloc16_to_child_id: Extracts the child ID from an RLOC16.
rloc16_to_router_id: Extracts the router ID from an RLOC16.
set_logging_level: Changes the logging level.

Type Aliases§

ChannelIndex: Channel index value. Identifies an individual radio channel for transmitting and receiving.
Decibels: Type for representing decibels, such as RSSI or transmit power.
Ip4Address: IPv4 address type
Ip6Address: IPv6 Address Type. Functional equivalent of otsys::otIp6Address.
MeshLocalPrefix: Mesh-Local Prefix.
NetifIndex: Network Interface Identifier.
PanId: 802.15.4 PAN Identifier. Same type as otsys::otPanId.
Result: Type returned by OpenThread calls.
ShortAddress: 802.15.4 Short Address. Same type as otsys::otShortAddress.

Module otCopy item path