1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240
//! Stabilizer network management module
//!
//! # Design
//! The stabilizer network architecture supports numerous layers to permit transmission of
//! telemetry (via MQTT), configuration of run-time settings (via MQTT + Miniconf), and live data
//! streaming over raw UDP/TCP sockets. This module encompasses the main processing routines
//! related to Stabilizer networking operations.
pub use heapless;
pub use miniconf;
pub use serde;
pub mod data_stream;
pub mod network_processor;
pub mod telemetry;
use crate::hardware::{
metadata::ApplicationMetadata, EthernetPhy, NetworkManager, NetworkStack,
SystemTimer,
};
use crate::settings::NetSettings;
use data_stream::{DataStream, FrameGenerator};
use network_processor::NetworkProcessor;
use telemetry::TelemetryClient;
use core::fmt::Write;
use heapless::String;
use miniconf::JsonCoreSlash;
use miniconf_mqtt::minimq;
use smoltcp_nal::embedded_nal::SocketAddr;
pub type NetworkReference =
smoltcp_nal::shared::NetworkStackProxy<'static, NetworkStack>;
pub struct MqttStorage {
telemetry: [u8; 2048],
settings: [u8; 1024],
}
impl Default for MqttStorage {
fn default() -> Self {
Self {
telemetry: [0u8; 2048],
settings: [0u8; 1024],
}
}
}
pub enum UpdateState {
NoChange,
Updated,
}
pub enum NetworkState {
SettingsChanged,
Updated,
NoChange,
}
/// A structure of Stabilizer's default network users.
pub struct NetworkUsers<S, const Y: usize>
where
for<'de> S: Default + JsonCoreSlash<'de, Y> + Clone,
{
pub miniconf: miniconf_mqtt::MqttClient<
'static,
S,
NetworkReference,
SystemTimer,
minimq::broker::NamedBroker<NetworkReference>,
Y,
>,
pub processor: NetworkProcessor,
stream: DataStream,
generator: Option<FrameGenerator>,
pub telemetry: TelemetryClient,
}
impl<S, const Y: usize> NetworkUsers<S, Y>
where
for<'de> S: Default + JsonCoreSlash<'de, Y> + Clone,
{
/// Construct Stabilizer's default network users.
///
/// # Args
/// * `stack` - The network stack that will be used to share with all network users.
/// * `phy` - The ethernet PHY connecting the network.
/// * `clock` - A `SystemTimer` implementing `Clock`.
/// * `app` - The name of the application.
/// * `net_settings` - The network-specific settings to use for the application.
/// * `metadata` - The application metadata
///
/// # Returns
/// A new struct of network users.
pub fn new(
stack: NetworkStack,
phy: EthernetPhy,
clock: SystemTimer,
app: &str,
net_settings: &NetSettings,
metadata: &'static ApplicationMetadata,
) -> Self {
let stack_manager =
cortex_m::singleton!(: NetworkManager = NetworkManager::new(stack))
.unwrap();
let processor =
NetworkProcessor::new(stack_manager.acquire_stack(), phy);
let prefix = get_device_prefix(app, &net_settings.id);
let store =
cortex_m::singleton!(: MqttStorage = MqttStorage::default())
.unwrap();
let named_broker = minimq::broker::NamedBroker::new(
&net_settings.broker,
stack_manager.acquire_stack(),
)
.unwrap();
let settings = miniconf_mqtt::MqttClient::new(
stack_manager.acquire_stack(),
&prefix,
clock,
minimq::ConfigBuilder::new(named_broker, &mut store.settings)
.client_id(&get_client_id(&net_settings.id, "settings"))
.unwrap(),
)
.unwrap();
let named_broker = minimq::broker::NamedBroker::new(
&net_settings.broker,
stack_manager.acquire_stack(),
)
.unwrap();
let mqtt = minimq::Minimq::new(
stack_manager.acquire_stack(),
clock,
minimq::ConfigBuilder::new(named_broker, &mut store.telemetry)
// The telemetry client doesn't receive any messages except MQTT control packets.
// As such, we don't need much of the buffer for RX.
.rx_buffer(minimq::config::BufferConfig::Maximum(100))
.client_id(&get_client_id(&net_settings.id, "tlm"))
.unwrap(),
);
let telemetry = TelemetryClient::new(mqtt, &prefix, metadata);
let (generator, stream) =
data_stream::setup_streaming(stack_manager.acquire_stack());
NetworkUsers {
miniconf: settings,
processor,
telemetry,
stream,
generator: Some(generator),
}
}
/// Enable live data streaming.
///
/// # Args
/// * `format` - A unique u8 code indicating the format of the data.
pub fn configure_streaming(
&mut self,
format: impl Into<u8>,
) -> FrameGenerator {
let mut generator = self.generator.take().unwrap();
generator.configure(format);
generator
}
/// Direct the stream to the provided remote target.
///
/// # Args
/// * `remote` - The destination for the streamed data.
pub fn direct_stream(&mut self, remote: SocketAddr) {
if self.generator.is_none() {
self.stream.set_remote(remote);
}
}
/// Update and process all of the network users state.
///
/// # Returns
/// An indication if any of the network users indicated a state change.
/// The SettingsChanged option contains the path of the settings that changed.
pub fn update(&mut self, settings: &mut S) -> NetworkState {
// Update the MQTT clients.
self.telemetry.update();
// Update the data stream.
if self.generator.is_none() {
self.stream.process();
}
// Poll for incoming data.
let poll_result = match self.processor.update() {
UpdateState::NoChange => NetworkState::NoChange,
UpdateState::Updated => NetworkState::Updated,
};
let res = self.miniconf.update(settings);
match res {
Ok(true) => NetworkState::SettingsChanged,
_ => poll_result,
}
}
}
/// Get an MQTT client ID for a client.
///
/// # Args
/// * `id` - The base client ID
/// * `mode` - The operating mode of this client. (i.e. tlm, settings)
///
/// # Returns
/// A client ID that may be used for MQTT client identification.
fn get_client_id(id: &str, mode: &str) -> String<64> {
let mut identifier = String::new();
write!(&mut identifier, "{id}-{mode}").unwrap();
identifier
}
/// Get the MQTT prefix of a device.
///
/// # Args
/// * `app` - The name of the application that is executing.
/// * `id` - The MQTT ID of the device.
///
/// # Returns
/// The MQTT prefix used for this device.
pub fn get_device_prefix(app: &str, id: &str) -> String<128> {
// Note(unwrap): The mac address + binary name must be short enough to fit into this string. If
// they are defined too long, this will panic and the device will fail to boot.
let mut prefix: String<128> = String::new();
write!(&mut prefix, "dt/sinara/{app}/{id}").unwrap();
prefix
}