a121_sys/lib.rs
1#![cfg_attr(not(any(test, feature = "std")), no_std)]
2#![allow(non_upper_case_globals)]
3#![allow(non_camel_case_types)]
4#![allow(non_snake_case)]
5#![allow(improper_ctypes)]
6#![allow(dead_code)]
7
8//! # a121-sys Crate Documentation
9//!
10//! Welcome to the `a121-sys` crate, providing raw FFI bindings for the Acconeer A121 radar sensor.
11//! This crate offers low-level access to the A121 sensor's capabilities, designed for embedded systems
12//! and `no_std` environments.
13//!
14//! ## Usage
15//!
16//! Add `a121-sys` to your `Cargo.toml`:
17//!
18//! ```toml
19//! [dependencies]
20//! # For real hardware
21//! a121-sys = { version = "0.8", features = ["distance", "presence"] }
22//!
23//! # For testing/development with stub library
24//! a121-sys = { version = "0.8", features = ["stub_library", "distance", "presence"] }
25//! ```
26//!
27//! ## Features
28//!
29//! - **distance**: Enable distance measurement functionality
30//! - **presence**: Enable presence detection functionality
31//! - **stub_library**: Use stub implementations for testing/development without hardware
32//! - **std**: Enable functionality requiring the standard library
33//!
34//! ## Library Requirements
35//!
36//! This crate requires the Acconeer A121 static libraries and a C cross compiler for the target
37//! (`arm-none-eabi-gcc` for Cortex-M). You can either:
38//!
39//! 1. Use the real libraries:
40//! - Obtain the official Acconeer A121 SDK
41//! - Set the `A121_RSS_LIB` (or `ACC_RSS_LIBS`) environment variable to the library location
42//!
43//! 2. Use stub libraries (for testing/development):
44//! - Enable the `stub_library` feature
45//!
46//! ## Logging Integration
47//!
48//! The crate provides a way to integrate with the sensor's native logging through a C log wrapper.
49//! Implement the `rust_log` function to capture log messages:
50//!
51//! ```no_run
52//! use core::ffi::c_char;
53//!
54//! #[no_mangle]
55//! pub extern "C" fn rust_log(level: u32, message: *const c_char) {
56//! // Your logging implementation here
57//! }
58//! ```
59//!
60//! ## Embedded Usage
61//!
62//! The crate is designed for embedded systems and supports:
63//!
64//! - `no_std` environments
65//! - Cortex-M4F (`thumbv7em-none-eabihf`) and Cortex-M33 (`thumbv8m.main-none-eabihf`) targets
66//! - ESP RISC-V and Xtensa targets, with ESP-IDF or bare metal
67//! - Both real hardware and stub implementations
68//!
69//! Example target configuration:
70//!
71//! ```toml
72//! [build]
73//! target = "thumbv7em-none-eabihf"
74//!
75//! [target.thumbv7em-none-eabihf]
76//! rustflags = [
77//! "-C", "link-arg=-mcpu=cortex-m4",
78//! "-C", "link-arg=-mthumb",
79//! "-C", "link-arg=-mfloat-abi=hard",
80//! "-C", "link-arg=-mfpu=fpv4-sp-d16",
81//! ]
82//! ```
83//!
84//! ## Safety
85//!
86//! This crate provides raw FFI bindings which are inherently unsafe. Users should:
87//!
88//! - Take care when implementing the logging callback
89//! - Ensure proper initialization of the sensor
90//! - Follow proper memory management practices
91//! - Consider using higher-level safe wrappers (like the `a121` crate)
92//!
93//! ## Development and Testing
94//!
95//! For development without hardware:
96//!
97//! 1. Enable the stub library feature:
98//! ```toml
99//! a121-sys = { version = "0.8", features = ["stub_library"] }
100//! ```
101//!
102//! 2. Install required toolchain:
103//! ```bash
104//! rustup target add thumbv7em-none-eabihf
105//! # Install ARM GCC toolchain for your platform
106//! ```
107//!
108//! ## Environment Variables
109//!
110//! - `ACC_RSS_LIBS`: Path to the Acconeer A121 libraries
111//! - `CPATH`: Additional C header paths (usually set automatically)
112//!
113//! ## Version Compatibility
114//!
115//! - Current bindings version: 1.13.0
116//! - Minimum Supported Rust Version (MSRV): 1.82.0
117//!
118
119use core::concat;
120use core::env;
121use core::include;
122
123include!(concat!(env!("OUT_DIR"), "/bindings.rs"));