meshtastic/lib.rs
1#![cfg_attr(docsrs, feature(doc_cfg))]
2
3//! A Rust library for communicating with and configuring Meshtastic devices.
4#[cfg(feature = "tokio")]
5pub(crate) mod connections;
6#[cfg(feature = "tokio")]
7pub(crate) mod errors_internal;
8#[cfg(feature = "tokio")]
9pub(crate) mod utils_internal;
10
11/// A re-export of the `prost::Message` trait, which is required to call the `encode`
12/// and `decode` methods on protocol buffer messages.
13pub use prost::Message;
14
15/// This module contains the main API for interacting with Meshtastic devices.
16/// This module exposes the `StreamApi` and `ConnectedStreamApi` structs, as well
17/// as helper states within the `state` module.
18///
19/// The user will create a new instance of the API through calling the `StreamApi::new()`
20/// method. This will return a new `StreamApi` instance. The only method that is exposed
21/// on this struct is the `connect` method. This is a compile-time check to force the user
22/// of the library to connect to a radio before attempting to send data onto the mesh.
23///
24/// If successful, the `connect` method will return a tuple of the `ConnectedStreamApi`
25/// instance, as well as a `PacketReceiver`. The `PacketReceiver` is a tokio channel
26/// that can be used to listen to incoming packets from the radio. Since the user is now
27/// connected to the radio. the resulting `ConnectedStreamApi` instance will then be able
28/// to access the `configure` method, as well as some additional low-level sender methods.
29///
30/// The `configure` method requests the current radio configuration, will return an updated
31/// instance of the `ConnectedStreamApi` struct. This resulting instance will then have access
32/// to the full set of API sender methods.
33///
34/// To disconnect from the radio, the user can call the `disconnect` method at any time.
35#[cfg(feature = "tokio")]
36pub mod api {
37 pub use crate::connections::stream_api::state;
38 pub use crate::connections::stream_api::ConnectedStreamApi;
39 pub use crate::connections::stream_api::StreamApi;
40 pub use crate::connections::stream_api::StreamHandle;
41}
42
43/// This module contains the global `Error` type of the library. This enum implements
44/// `std::error::Error`, `std::fmt::Display`, and `std::fmt::Debug`. This enum is used to
45/// represent all errors that can occur within the library.
46#[cfg(feature = "tokio")]
47pub mod errors {
48 pub use crate::errors_internal::Error;
49}
50
51/// This module contains the structs, enums, and traits that are necessary to define the behavior
52/// of packets within the library. This module exposes the `PacketDestination` enum, the `PacketRouter`
53/// trait, and the `PacketReceiver` type.
54///
55/// The `PacketDestination` enum is used to define the destination of a packet. The enum defines three possible
56/// destinations for packets sent to the radio by the library:
57///
58/// * `PacketDestination::Local` - This destination is used for packets that are intended to be processed locally
59/// by the radio and not to be forwarded to other nodes. An example of this would be local configuration packets.
60/// * `PacketDestination::Broadcast` - This destination is used for packets that are intended to be broadcast to all
61/// nodes in the mesh. This is the default enum variant. Text messages are commonly broadcasted to the entire mesh.
62/// * `PacketDestination::Node(u32)` - This destination is used for packets that are intended to be sent to a specific
63/// node in the mesh. The `u32` value is the node id of the node that the packet should be sent to. This is commonly
64/// used for direct text messages.
65///
66/// The `PacketRouter` trait defines the behavior of a struct that is able to route mesh packets. This trait is used
67/// to allow for the echoing of mesh packets within the `send_mesh_packet` method of the `ConnectedStreamApi` struct.
68///
69/// The `PacketReceiver` type defines the type of the tokio channel that is used to receive decoded packets from the radio.
70/// This is intended to simplify the complexity of the underlying channel type.
71#[cfg(feature = "tokio")]
72pub mod packet {
73 pub use crate::connections::handlers::CLIENT_HEARTBEAT_INTERVAL;
74 pub use crate::connections::PacketDestination;
75 pub use crate::connections::PacketRouter;
76
77 /// A type alias for the tokio channel that is used to receive decoded `protobufs::FromRadio` packets from the radio.
78 pub type PacketReceiver = tokio::sync::mpsc::UnboundedReceiver<crate::protobufs::FromRadio>;
79}
80
81/// This module contains structs and enums that are generated from the protocol buffer (protobuf)
82/// definitions of the `meshtastic/protobufs` Git submodule. These structs and enums
83/// are not edited directly, but are instead generated at build time.
84pub mod protobufs {
85 #![allow(missing_docs)]
86 #![allow(non_snake_case)]
87 #![allow(unknown_lints)]
88 #![allow(clippy::empty_docs)]
89 #![allow(clippy::doc_lazy_continuation)]
90 #![allow(clippy::doc_overindented_list_items)]
91 include!("generated/meshtastic.rs");
92}
93
94/// This module re-exports the `specta` crate, which is used to generate TypeScript
95/// type definitions from the protobuf definitions of the `meshtastic/protobufs` Git submodule.
96/// This module is only compiled if the `ts-gen` feature is enabled.
97///
98/// The `specta` crate exposes functionality that allows users of the library to export a
99/// TypeScript type definition file containing TypeScript types for all members of the
100/// `protobufs` module. This allows for complete type safety when interfacing with a TypeScript
101/// application.
102#[cfg(feature = "ts-gen")]
103pub mod ts {
104 #![allow(non_snake_case)]
105
106 /// A re-export of the `specta` crate, which is used to generate TypeScript type definitions
107 /// from the protobuf definitions of the `meshtastic/protobufs` Git submodule.
108 pub use specta;
109}
110
111/// This module exposes utility functions that aren't fundamental to the operation of the
112/// library, but simplify the configuration and usage of member methods.
113///
114/// The `DEFAULT_DTR_PIN_STATE` and `DEFAULT_RTS_PIN_STATE` constants are used to define the
115/// default pin states of the DTR and RTS pins of the serial connection. The `DEFAULT_SERIAL_BAUD`
116/// constant is used to define the default baud rate of incoming serial connections created by the
117/// `build_serial_stream` method.
118///
119/// Additionally, this module exposes helper methods that are used internally to format data packets.
120/// These methods are intended for use by more advanced users.
121///
122/// The `stream` module contains helper methods that are used to build connection stream instances.
123#[cfg(feature = "tokio")]
124pub mod utils {
125 pub use crate::utils_internal::DEFAULT_DTR_PIN_STATE;
126 pub use crate::utils_internal::DEFAULT_RTS_PIN_STATE;
127 pub use crate::utils_internal::DEFAULT_SERIAL_BAUD;
128
129 pub use crate::utils_internal::current_epoch_secs_u32;
130 pub use crate::utils_internal::format_data_packet;
131 pub use crate::utils_internal::generate_rand_id;
132 pub use crate::utils_internal::strip_data_packet_header;
133
134 /// This module contains utility functions that are used to build the `Stream` instances
135 /// that are used to connect to the radio. Since the `StreamApi::connect` method only
136 /// requires that streams implement the `tokio::io::AsyncReadExt` and `tokio::io::AsyncWriteExt`
137 /// methods, there are countless ways a user could theoretically connect to a radio.
138 ///
139 /// This module exposes the `build_serial_stream` and `build_tcp_stream` methods, which
140 /// simplify the process of initializing a connection stream. The vast majority of users will
141 /// only need to use these two methods to connect to a radio. The `available_serial_ports` method
142 /// can also be used to list all available serial ports on the host machine.
143 pub mod stream {
144 #[cfg(feature = "bluetooth-le")]
145 pub use crate::connections::ble_handler::BleDevice;
146 #[cfg(feature = "bluetooth-le")]
147 pub use crate::connections::ble_handler::BleId;
148 #[cfg(feature = "bluetooth-le")]
149 pub use crate::utils_internal::available_ble_devices;
150 pub use crate::utils_internal::available_serial_ports;
151 #[cfg(feature = "bluetooth-le")]
152 pub use crate::utils_internal::build_ble_stream;
153 pub use crate::utils_internal::build_serial_stream;
154 pub use crate::utils_internal::build_tcp_stream;
155 }
156}
157
158/// This module exposes wrappers around common types that are used throughout the library.
159/// These wrappers are used to simplify the API of the library, and to provide additional
160/// type safety.
161///
162/// The `NodeId` struct is a wrapper around a `u32` value that represents the ID of a node
163/// in the mesh. This struct is used to provide additional type safety when specifying
164/// node IDs.
165///
166/// The `MeshChannel` enum is a wrapper around a `u32` value that represents the channel
167/// of the mesh. This struct is used to provide additional type safety when specifying
168/// mesh channels, as it will only allow channels with indices between 0 and 7, inclusive.
169///
170/// The `EncodedMeshPacketData` struct is a wrapper around a `Vec<u8>` value that represents
171/// the payload data of a mesh packet (e.g., a text message).
172///
173/// The `EncodedToRadioPacket` struct is a wrapper around a `Vec<u8>` value that represents
174/// the payload data of a packet that is intended to be sent to the radio. This struct
175/// **does not** represent the full packet that is sent to the radio, as it does not include
176/// the required packet header.
177///
178/// The `EncodedToRadioPacketWithHeader` struct is a wrapper around a `Vec<u8>` value that
179/// represents the payload data of a packet that is intended to be sent to the radio. This
180/// struct includes the required packet header, and can be sent to the radio.
181#[cfg(feature = "tokio")]
182pub mod types {
183 pub use crate::connections::wrappers::encoded_data::EncodedMeshPacketData;
184 pub use crate::connections::wrappers::encoded_data::EncodedToRadioPacket;
185 pub use crate::connections::wrappers::encoded_data::EncodedToRadioPacketWithHeader;
186 pub use crate::connections::wrappers::encoded_data::IncomingStreamData;
187 pub use crate::connections::wrappers::mesh_channel::MeshChannel;
188 pub use crate::connections::wrappers::NodeId;
189}