poststation_fw_icd/
lib.rs

1//! Reserved or "special" types and interfaces within Poststation
2//!
3//! ## NOTE
4//!
5//! For now, there is no way to "import" these definitions directly, so they
6//! are provided as examples, and the types are expected to be used directly.
7//!
8//! See [postcard-rpc#71] for more information.
9//!
10//! [postcard-rpc#71]: https://github.com/jamesmunns/postcard-rpc/issues/71
11
12#![cfg_attr(not(feature = "use-std"), no_std)]
13
14
15#[allow(unused_imports)]
16use postcard_rpc::{endpoint, topic};
17use serde::{Serialize, Deserialize};
18use postcard_schema::Schema;
19
20/// # Unique ID
21///
22/// This is an endpoint for identifying the unique ID of the device. It is
23/// expected to be unique across all devices connected to a Poststation server.
24/// This value is expected to be constant over the entire lifetime of the device.
25///
26/// Common sources of this unique ID are:
27///
28/// * Serial number or unique ID of the processor
29/// * Serial number or unique ID of the external flash
30/// * Factory or programmed ID stored in non-volatile memory
31///
32/// If your device provides more or less than 64-bits of unique values, it is
33/// recommended to use a deterministic way to extend or shorten the value, for
34/// example taking the least significant bytes (to shorten) or hashing the available
35/// information (to lengthen), for example using fnv64a.
36pub mod unique_id {
37    use super::*;
38    pub type UniqueId = u64;
39    endpoint!(GetUniqueIdEndpoint, (), UniqueId, "poststation/unique_id/get");
40}
41
42/// # Bridging
43///
44/// This is a currently experimental interface for transparent bridging, for
45/// example over a radio link, where one device directly connected to Poststation
46/// will maintain connections to other devices.
47///
48/// For example: an nRF52840 is used as a bridge, and connected via USB to the
49/// PC running Poststation. The bridge then maintains a wireless network to other
50/// devices with postcard-rpc, allowing the remote wireless devices to "appear as if"
51/// they are directly connected to the PC running Poststation.
52pub mod bridging {
53    use super::*;
54    // | Bridge2HostTopic          | ProxyMessage<'a>  | "bridge/to/host"  | cfg(not(feature = "use-std"))     |
55    // | Bridge2HostTopic          | ProxyMessage      | "bridge/to/host"  | cfg(feature = "use-std")          |
56    // | BridgeTableTopic          | BridgeTable       | "bridge/table"    |                                   |
57
58    // TODO: The endpoint! macro doesn't support borrowing
59    // #[cfg(not(feature = "use-std"))]
60    // endpoint!(Host2BridgeEndpoint, ProxyMessage<'a>, ProxyResult, "poststation/host/to/bridge");
61
62    #[cfg(feature = "use-std")]
63    endpoint!(Host2BridgeEndpoint, ProxyMessage, ProxyResult, "poststation/host/to/bridge");
64
65    // TODO: The topic! macro doesn't support borrowing
66    // #[cfg(not(feature = "use-std"))]
67    // topic!(Bridge2HostTopic, ProxyMessage<'a>, "poststation/bridge/to/host");
68
69    #[cfg(feature = "use-std")]
70    topic!(Bridge2HostTopic, ProxyMessage, "poststation/bridge/to/host");
71
72    topic!(BridgeTableTopic, BridgeTable, "poststation/bridge/table");
73
74
75    /// A device Unique ID, stored as a little-endian array of bytes
76    pub type UniqueIdBytes = [u8; 8];
77
78    /// A message proxied to or from a remote device
79    #[cfg(not(feature = "use-std"))]
80    #[derive(Debug, Serialize, Deserialize, Schema)]
81    pub struct ProxyMessage<'a> {
82        /// The unique id of the remote device
83        pub serial: UniqueIdBytes,
84        /// The postcard-rpc encoded payload of the message
85        pub msg: &'a [u8],
86    }
87
88    /// A message proxied to or from a remote device
89    #[cfg(feature = "use-std")]
90    #[derive(Debug, Serialize, Deserialize, Schema)]
91    pub struct ProxyMessage {
92        /// The unique id of the remote device
93        pub serial: UniqueIdBytes,
94        /// The postcard-rpc encoded payload of the message
95        pub msg: Vec<u8>,
96    }
97
98    /// The table of currently connected remote devices
99    // TODO: This is not right, it's hardcoded to my esb bridge stuff
100    #[cfg(not(feature = "use-std"))]
101    #[derive(Debug, Serialize, Deserialize, Schema)]
102    pub struct BridgeTable {
103        pub sers: heapless::Vec<UniqueIdBytes, 7>,
104    }
105
106    /// The table of currently connected remote devices
107    #[cfg(feature = "use-std")]
108    #[derive(Debug, Serialize, Deserialize, Schema)]
109    pub struct BridgeTable {
110        pub sers: Vec<UniqueIdBytes>,
111    }
112
113    /// Error when proxying
114    #[derive(Debug, Serialize, Deserialize, Schema)]
115    pub enum ProxyError {
116        UnknownDevice,
117    }
118
119    pub type ProxyResult = Result<(), ProxyError>;
120
121}
poststation_fw_icd/lib.rs

poststation_fw_icd/
lib.rs
