tosca_os/
lib.rs

1//! `tosca-os` is a library crate for building firmware for `tosca` devices
2//! running on operating systems.
3//!
4//! This crate targets devices that require more resources than typical embedded
5//! systems, such as computing time, memory capacity, and interaction
6//! with external components.
7//!
8//! Currently, only firmware for `x86_64` and `ARM` architectures is supported
9//! and covered by automated tests.
10//!
11//! Device firmware consists of a description and a set of tasks, both exposed
12//! through a client-server architecture in which the firmware operates as the
13//! server and its controller as the client.
14//!
15//! A device description is defined as a sequence of fields, such as the
16//! device name, the device kind, and other data used to establish a
17//! connection with the a controller.
18//!
19//! When a controller makes a request to the firmware through route, the
20//! firmware executes the corresponding task and sends a response! back to the
21//! controller.
22//! Routes may also accept parameters to configure tasks.
23//!
24//! Each route may have zero or more associated hazards, representing potential
25//! risks during task execution. Even if no hazards are declared, a route may
26//! still pose unknown risks to the device.
27//! In such cases, the controller must decide whether to allow or block the
28//! request based on its privacy policy.
29//!
30//! This crate **cannot** determine the outcome of device tasks at compile
31//! time, as they depend on the runtime environment. Therefore, hazards
32//! only informs a controller of the **possible** risks that might arise.
33//!
34//! An `std` environment is required to obtain full crate functionality.
35
36#![deny(unsafe_code)]
37#![deny(missing_docs)]
38
39/// All supported device types.
40pub mod devices;
41
42/// General device definition along with its methods.
43pub mod device;
44/// Error management.
45pub mod error;
46/// All responses kinds along with their payloads.
47pub mod responses;
48/// The firmware server.
49pub mod server;
50/// The discovery service used to make the firmware detectable on the network.
51pub mod service {
52    pub use super::services::{ServiceConfig, TransportProtocol};
53}
54
55/// Utilities for parsing request parameters and constructing responses.
56pub mod extract {
57    pub use axum::extract::{FromRef, Json, Path, State};
58    pub use axum::http::header;
59}
60
61mod mac;
62mod services;