piper_sdk/
lib.rs

1//! Piper SDK - 松灵机械臂 Rust SDK
2//!
3//! 高性能、跨平台、零抽象开销的 Rust SDK，专用于松灵 Piper 机械臂的高频力控（>1kHz）。
4//!
5//! # 架构设计
6//!
7//! 本 SDK 采用分层架构，从底层到高层：
8//!
9//! - **CAN 层** (`can`): CAN 硬件抽象，支持 SocketCAN 和 GS-USB
10//! - **协议层** (`protocol`): 类型安全的协议编码/解码
11//! - **驱动层** (`driver`): IO 线程管理、状态同步、帧解析
12//! - **客户端层** (`client`): 类型安全、易用的控制接口
13//!
14//! # 快速开始
15//!
16//! 大多数用户应该使用高层 API（客户端接口）：
17//!
18//! ```rust
19//! use piper_sdk::prelude::*;
20//! // 或
21//! use piper_sdk::{Piper, Observer};
22//! ```
23//!
24//! 需要直接控制 CAN 帧或需要更高性能的用户可以使用驱动层：
25//!
26//! ```rust
27//! use piper_sdk::driver::{Piper as Driver, PiperBuilder};
28//! ```
29
30// 内部模块结构（重新导出各个层）
31pub mod can {
32    pub use piper_can::*;
33}
34
35pub mod protocol {
36    pub use piper_protocol::*;
37}
38
39pub mod driver {
40    pub use piper_driver::*;
41}
42
43pub mod client {
44    pub use piper_client::*;
45}
46
47// Prelude 模块
48pub mod prelude;
49
50// --- 用户以此为界 ---
51
52// CAN 层常用类型
53pub use can::{CanAdapter, CanError, PiperFrame};
54
55// 协议层错误
56pub use protocol::ProtocolError;
57
58// 驱动层（高级用户使用）- 通过模块路径访问，避免命名冲突
59// 注意：不直接导出 driver::Piper，因为与 client::Piper 冲突
60// 用户可以通过 driver::Piper 或类型别名访问
61pub use driver::DriverError;
62
63// 客户端层（普通用户使用）- 这是推荐的入口点
64// 导出 client::Piper 为 Piper（这是大多数用户应该使用的）
65pub use client::Piper; // Type State Pattern 的状态机
66pub use client::{
67    Observer,
68    PiperBuilder, // Client 层 Builder（推荐使用）
69                  // 类型系统通过 types 模块导出
70};
71
72// 导出 recording 模块的常用类型
73pub use client::recording::{
74    RecordingConfig, RecordingHandle, RecordingMetadata, RecordingStats, StopCondition,
75};
76
77// 类型别名：为驱动层提供清晰的别名
78pub type Driver = driver::Piper; // 高级用户可以使用这个别名
79
80// ============================================================
81// 日志初始化宏
82// ============================================================
83
84/// 初始化日志系统（便捷宏）
85///
86/// ## 功能
87///
88/// - 兼容 `log` crate（通过 `tracing-log::LogTracer`）
89/// - 从 `RUST_LOG` 环境变量读取日志级别
90/// - 默认级别：`piper_sdk=info`
91/// - 格式：compact，隐藏 target（易读）
92///
93/// ## 使用示例
94///
95/// ```rust,no_run
96/// use piper_sdk::prelude::*;
97///
98/// fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
99///     // 在 main 函数开头初始化日志
100///     piper_sdk::init_logger!();
101///
102///     // 连接机器人
103///     let driver = PiperBuilder::new().interface("can0").build()?;
104///
105///     // 现在可以使用 tracing::info!, tracing::warn! 等宏
106///     tracing::info!("Connected to robot");
107///
108///     Ok(())
109/// }
110/// ```
111#[macro_export]
112macro_rules! init_logger {
113    () => {
114        // ✅ 兼容旧 log crate 的宏（如 log::info!）
115        let _ = ::tracing_log::LogTracer::init();
116
117        // 使用默认配置，支持 RUST_LOG 环境变量
118        if ::std::env::var("RUST_LOG").is_ok() {
119            // 用户设置了 RUST_LOG，使用他们的配置
120            ::tracing_subscriber::fmt().with_target(false).compact().init();
121        } else {
122            // 使用默认级别 info
123            ::tracing_subscriber::fmt()
124                .with_max_level(::tracing::Level::INFO)
125                .with_target(false)
126                .compact()
127                .init();
128        }
129    };
130}
piper_sdk/lib.rs

piper_sdk/
lib.rs
