arduino-sdk-sys

Rust bindings for arduino.

it is a somewhat idiomatic Rust wrapper for arduino core/external libraries bindings, target is use arduino c/c++ library in rust project.

Released under the Apache License 2.0.

features

the prettify_bindgen Cargo feature is disable defautly, it need clang-rs. if this feature enable, the binding output will be more simple, because it will limit the output only in the scope of external libraries headers, not others contents that belongs to "#include ...".

preprequirements

• installed arduino-cli, or The Arduino IDE 2.x application(it now provides the graphical user interface and the arduino-cli tool provides the command line interface.)

• arduino-cli is in the PATH env. this crate need arduino-cli to get the all information about arduino sdk. e.g. data/user directory, the installed plaform version related the to target fqbn(VENDOR:ARCHITECTURE:BOARD_ID), and so on.

there are many ways to install arduino-cli. for example, using scoop install arduino-cli in windows, more installation instruction pls refer arduino-cli installation

Note: before use this create, pls confirm the target fqbn has installed. for example, in my test envirement, it has installed "arduino:avr" core(through arduino-cli core install arduino:avr), or use arduino-cli board details -b <FQBN> command to check:

$ arduino-cli core list
ID              Installed Latest Name
arduino:avr     1.8.6     1.8.6  Arduino AVR Boards
$ arduino-cli board listall
Board Name                       FQBN
Adafruit Circuit Playground      arduino:avr:circuitplay32u4cat
Arduino BT                       arduino:avr:bt
...
Arduino Robot Motor              arduino:avr:robotMotor
Arduino Uno                      arduino:avr:uno
...
Linino One                       arduino:avr:one

Dependencies

this crate will wrapper libarduino_core.a and libarduino_external.a to be a rlib used by the down-stream app. those libraries is generated by this crate. how to compile them depends on the arduino configurations(platform.txt, boards.txt, and package_index.json) and the down-stream configuration. the down-stream configuration detials will be descripted on blow.

the libarduino_core.a will stored in this crate CARGO_MANIFEST_DIR/arudino-lib/<arduino fqbn info>/boardid, to decreae compile time in the future.

the libarduino_external.a is stored in down-stream app OUT_DIR. it means, when the down-stream app re-build, it will generated again. the reason is its compile time is acceptable.

this crate only generate bindings for the external libraris listed in "external_libraries" of the down-stream configuration. the external libraries source must be located in arduino user directory (sketchbook).

Environment Variables

when down-steam app use this crate, firstly, the down-steam app need to add this crate in its dependencies. then "ARDUINO_SDK_CONFIG" var definition need to be defined in Cargo’s configuration file of down-stream App.

[env]
# Value is relative to .cargo directory containing `config.toml`, make absolute
ARDUINO_SDK_CONFIG = { value = "custom.yaml", relative = true }

# except fqbn, others are all optional.
# fqbn format is: VENDOR:ARCHITECTURE:BOARD_ID[:MENU_ID=OPTION_ID[,MENU2_ID=OPTION_ID ...]]
# e.g. arduino:avr:uno
# e.g. arduino:esp32:nano_nora
fqbn: arduino:avr:diecimila:cpu=atmega168

# c/cpp/asm flags used for core and libraries, the for_core only for core module
compile_flags:
    #core dedicated flags
    for_core:
    #  c file compile flag list
    c:
    # cpp file compile flag list
    cpp:
    # S file compile flag list
    asm:
#external libraries ,that located in user directory (sketchbook)
external_libraries:
    - LiquidCrystal_I2C
    - Servo

fqbn: arduino:esp32:nano_nora

# c/cpp/asm flags used for core and libraries, the for_core only for core module
compile_flags:
    #core dedicated flags
    for_core:
        - -DARDUINO_CORE_BUILD

compile and Linking

libarduino_core.a and libarduino_external.a are compiled by the compile flags form arduino platform.txt configuration and down-stream app configuration. compile/archive tool is from arduino platform.txt.

• in arduino platform.txt, this crate will get recipe.c.o.pattern/recipe.cpp.o.pattern/recipe.S.o.pattern and split them to get the compile flags.

• in down-stream app configuration, this crate will get "compile_flags".

Note: before compile, this crate build.rs will remove "-lto" flag, if input flags(from arduino platform.txt or down-stream configuration) contains it. because it will arise problem that down-stream app can not link this crate as a rlib.

scope comment:

• libarduino_core.a scope: {build.core.path}, {build.variant.path}, and "<target-fqbn-platform-path>/libraries".

• libarduino_external.a scope: listed libraies in "<arduino-user>/libraries"

binding comment:

• only generate binding for libarduino_external.a.
• if you want to use some api in libarduino_core.a, you can manual provide the binding.

down-stream app demo

Let's create a empty app. for example, through cargo generate --git https://github.com/Rahix/avr-hal-template.git ,specify the project name and select the board type, then you will get a rust down-stream app.

Let's update app's Cargo.toml: add arduino-sys dependency

Let's update app's .cargo/config.toml: add ARDUINO_SDK_CONFIG env, and create the related custom.yaml file.

let's update main.rs. e.g.

#![no_std]
#![no_main]
extern crate arduino_sys;
use panic_halt as _;
use arduino_sys::{servo,init,liquidcrystal_i2c};
#[arduino_hal::entry]
fn main() -> ! {
    unsafe{
    //  it is Arduino framework provided function to initialize the board. 
    // We would need to call it in rust as well before we start using any Arduino library    
    init();
    let mut s=servo::Servo::new();

    }
    let dp = arduino_hal::Peripherals::take().unwrap();
    let pins = arduino_hal::pins!(dp);

let's build the app.