cu29/
lib.rs

1//! # Copper Runtime & SDK
2//!
3//! Think of Copper as a robotics game engine: define a task graph, compile once,
4//! and get deterministic execution, unified logging, and sub-microsecond
5//! latency from Linux workstations all the way down to bare-metal MPU builds.
6//!
7//! ## Quick start
8//!
9//! ```bash
10//! cargo install cargo-generate
11//! git clone https://github.com/copper-project/copper-rs
12//! cd copper-rs/templates
13//! cargo cunew /path/to/my_robot   # scaffolds a full Copper project
14//! ```
15//!
16//! It will generate a minimal Copper robot project at `/path/to/my_robot`. `cargo build` should
17//! compile it out of the box.
18//!
19//! ## Feature flags
20//!
21//! - `default` = `["std", "textlogs", "units"]`
22//! - `units`: exposes `cu29::units` (re-export of `cu29-units`)
23//! - `std`: host/runtime support
24//! - `reflect`: reflection support for runtime and units types
25//! - `textlogs`: text logging derive support
26//! - `remote-debug`: remote debug transport support
27//!
28//! ## Concepts behind Copper
29//!
30//! Check out the [Copper Wiki](https://github.com/copper-project/copper-rs/wiki) to understand the
31//! deployments concepts, task lifecycle, available components, etc ...
32//!
33//! ## More examples to get you started
34//!
35//! - `examples/cu_caterpillar`: a minimal running example passing around booleans.
36//! - `examples/cu_rp_balancebot`: a more complete example try Copper without hardware via
37//!   `cargo install cu-rp-balancebot` + `balancebot-sim` (Bevy + Avian3d).
38//!
39//! ## Key traits and structs to check out
40//!
41//! - `cu29_runtime::app::CuApp`: the main trait the copper runtime will expose to run your application. (when run() etc .. is coming from)
42//! - `cu29_runtime::config::CuConfig`: the configuration of your runtime
43//! - `cu29_runtime::cutask::CuTask`: the core trait and helpers to implement your own tasks.
44//! - `cu29_runtime::cubridge::CuBridge`: the trait to implement bridges to hardware or other software.
45//! - `cu29_runtime::curuntime::CuRuntime`: the runtime that manages task execution.
46//! - `cu29_runtime::simulation`: This will explain how to hook up your tasks to a simulation environment.
47//!
48//! Need help or want to show what you're building? Join
49//! [Discord](https://discord.gg/VkCG7Sb9Kw) and hop into the #general channel.
50//!
51
52#![cfg_attr(not(feature = "std"), no_std)]
53#[cfg(not(feature = "std"))]
54extern crate alloc;
55
56pub use cu29_derive::{bundle_resources, resources};
57pub use cu29_runtime::config;
58pub use cu29_runtime::context;
59pub use cu29_runtime::copperlist;
60#[cfg(feature = "std")]
61pub use cu29_runtime::cuasynctask;
62pub use cu29_runtime::cubridge;
63pub use cu29_runtime::curuntime;
64pub use cu29_runtime::cutask;
65#[cfg(feature = "std")]
66pub use cu29_runtime::debug;
67pub use cu29_runtime::input_msg;
68pub use cu29_runtime::monitoring;
69pub use cu29_runtime::output_msg;
70pub use cu29_runtime::payload;
71pub use cu29_runtime::reflect;
72pub use cu29_runtime::reflect as bevy_reflect;
73#[cfg(feature = "remote-debug")]
74pub use cu29_runtime::remote_debug;
75pub use cu29_runtime::resource;
76pub use cu29_runtime::rx_channels;
77#[cfg(feature = "std")]
78pub use cu29_runtime::simulation;
79pub use cu29_runtime::tx_channels;
80
81#[cfg(feature = "rtsan")]
82pub mod rtsan {
83    pub use rtsan_standalone::*;
84}
85
86#[cfg(not(feature = "rtsan"))]
87pub mod rtsan {
88    use core::ffi::CStr;
89
90    #[derive(Default)]
91    pub struct ScopedSanitizeRealtime;
92
93    #[derive(Default)]
94    pub struct ScopedDisabler;
95
96    #[inline]
97    pub fn realtime_enter() {}
98
99    #[inline]
100    pub fn realtime_exit() {}
101
102    #[inline]
103    pub fn disable() {}
104
105    #[inline]
106    pub fn enable() {}
107
108    #[inline]
109    pub fn ensure_initialized() {}
110
111    #[allow(unused_variables)]
112    pub fn notify_blocking_call(_function_name: &'static CStr) {}
113}
114
115pub use bincode;
116pub use cu29_clock as clock;
117#[cfg(feature = "units")]
118pub use cu29_units as units;
119#[cfg(feature = "defmt")]
120pub mod defmt {
121    pub use defmt::{debug, error, info, warn};
122}
123#[cfg(feature = "std")]
124pub use cu29_runtime::config::read_configuration;
125pub use cu29_traits::*;
126
127#[cfg(feature = "std")]
128pub use rayon;
129
130// defmt shims re-exported for proc-macro call sites
131#[cfg(all(feature = "defmt", not(feature = "std")))]
132#[macro_export]
133macro_rules! defmt_debug {
134    ($fmt:literal $(, $arg:expr)* $(,)?) => {
135        $crate::defmt::debug!($fmt $(, $arg)*);
136    }
137}
138#[cfg(not(all(feature = "defmt", not(feature = "std"))))]
139#[macro_export]
140macro_rules! defmt_debug {
141    ($($tt:tt)*) => {{}};
142}
143
144#[cfg(all(feature = "defmt", not(feature = "std")))]
145#[macro_export]
146macro_rules! defmt_info {
147    ($fmt:literal $(, $arg:expr)* $(,)?) => {
148        $crate::defmt::info!($fmt $(, $arg)*);
149    }
150}
151#[cfg(not(all(feature = "defmt", not(feature = "std"))))]
152#[macro_export]
153macro_rules! defmt_info {
154    ($($tt:tt)*) => {{}};
155}
156
157#[cfg(all(feature = "defmt", not(feature = "std")))]
158#[macro_export]
159macro_rules! defmt_warn {
160    ($fmt:literal $(, $arg:expr)* $(,)?) => {
161        $crate::defmt::warn!($fmt $(, $arg)*);
162    }
163}
164#[cfg(not(all(feature = "defmt", not(feature = "std"))))]
165#[macro_export]
166macro_rules! defmt_warn {
167    ($($tt:tt)*) => {{}};
168}
169
170#[cfg(all(feature = "defmt", not(feature = "std")))]
171#[macro_export]
172macro_rules! defmt_error {
173    ($fmt:literal $(, $arg:expr)* $(,)?) => {
174        $crate::defmt::error!($fmt $(, $arg)*);
175    }
176}
177#[cfg(not(all(feature = "defmt", not(feature = "std"))))]
178#[macro_export]
179macro_rules! defmt_error {
180    ($($tt:tt)*) => {{}};
181}
182
183pub mod prelude {
184    pub use crate::bevy_reflect;
185    #[cfg(feature = "units")]
186    pub use crate::units;
187    pub use crate::{defmt_debug, defmt_error, defmt_info, defmt_warn};
188    #[cfg(feature = "std")]
189    pub use ctrlc;
190    pub use cu29_clock::*;
191    pub use cu29_derive::*; // includes resources! proc macro
192    pub use cu29_log::*;
193    pub use cu29_log::{
194        __cu29_defmt_debug, __cu29_defmt_error, __cu29_defmt_info, __cu29_defmt_warn,
195    };
196    pub use cu29_log_derive::*;
197    pub use cu29_log_runtime::*;
198    pub use cu29_runtime::app::*;
199    pub use cu29_runtime::config::*;
200    pub use cu29_runtime::context::*;
201    pub use cu29_runtime::copperlist::*;
202    pub use cu29_runtime::cubridge::*;
203    pub use cu29_runtime::curuntime::*;
204    pub use cu29_runtime::cutask::*;
205    #[cfg(feature = "std")]
206    pub use cu29_runtime::debug::*;
207    pub use cu29_runtime::input_msg;
208    pub use cu29_runtime::monitoring::*;
209    pub use cu29_runtime::output_msg;
210    pub use cu29_runtime::payload::*;
211    #[cfg(feature = "reflect")]
212    pub use cu29_runtime::reflect::serde as reflect_serde;
213    #[cfg(feature = "reflect")]
214    pub use cu29_runtime::reflect::serde::{
215        ReflectSerializer, SerializationData, TypedReflectSerializer,
216    };
217    pub use cu29_runtime::reflect::{
218        GetTypeRegistration, Reflect, ReflectTaskIntrospection, ReflectTypePath, TypeInfo,
219        TypePath, TypeRegistry, dump_type_registry_schema,
220    };
221    #[cfg(feature = "remote-debug")]
222    pub use cu29_runtime::remote_debug::*;
223    pub use cu29_runtime::resource::*;
224    pub use cu29_runtime::rx_channels;
225    #[cfg(feature = "std")]
226    pub use cu29_runtime::simulation::*;
227    pub use cu29_runtime::tx_channels;
228    pub use cu29_runtime::*;
229    pub use cu29_traits::*;
230    pub use cu29_unifiedlog::*;
231    pub use cu29_value::Value;
232    pub use cu29_value::to_value;
233    #[cfg(feature = "std")]
234    pub use pool::*;
235    pub use serde::Serialize;
236}
cu29/lib.rs

cu29/
lib.rs
