4 releases
0.1.3 | Nov 5, 2022 |
---|---|
0.1.2 | Oct 22, 2022 |
0.1.1 | Oct 17, 2022 |
0.1.0 | Oct 7, 2022 |
#8 in #flipper-zero
Used in 3 crates
(2 directly)
4KB
Rusty API for Flipper Zero
🦀 ❤️🔥 🐬
Project Structure
This project is composed of the following crates:
-
flipper0-sys
: CFFI bindings. -
flipper0
: High-level idiomatic bindings and wrappers that almost looks like as std-types. -
other support crates, see docs inside
- flipper0-build-cfg: Constants and configuration for build system
- flipper0-fam-build: Manifest generator
- flipper0-fap-build: Application Package build utils
- fam: Flipper Application Package manifest format
- flipper0-macro: Proc-macro
#[main]
for register and rustify entry point function.
Bindings for Flipper Zero
Automatically generated bindings (or "externs") for Flipper Zero Fw with some little hand-crafted wrappers and additions as upper abstraction layer.
See crate description and examples.
State
Current state of the project is WiP. Highly & dirty work-in-progress. Any contribution are appreciated, you know.
Build
There's three options: using pre-built bindings, build from existing clone of flipper-firmware repo, clone and build from source.
Using pre-built bindings
Needed:
- Rust toolchain (
nightly
channel) - target
thumbv7em-none-eabihf
libclang
for bindgen (because bindgen as build-dependency can't be optional)
Example
crate manifest:
[dependencies]
flipper0-sys = "*"
lib.rs:
#![crate_type = "staticlib"] #![no_main] #![no_std]
extern crate flipper0_sys;
use flipper0_sys::ffi::*;
#[no_mangle]
pub unsafe extern "C" fn init(_: *mut u8) -> i32 {
static MESSAGE: &[u8] = b"Hello, World!";
furi_thread_stdout_write(MESSAGE.as_ptr() as _, MESSAGE.len());
0
}
Build with cargo +nightly build --target=thumbv7em-none-eabihf
.
Build bindings from source
Needed:
- Rust toolchain (
nightly
channel) - target
thumbv7em-none-eabihf
libclang
for bindgen- clone of Flipper Zero firmware
- Env var
FLIPPER_FW_SRC_PATH
points to the root of the fw repo
- Env var
- ARM toolchain, run
fbt
to easily get it
crate manifest:
[dependencies.flipper0-sys]
version = "*"
default-features = false # disable prebuild
features = [
"allocator-global",
"oom-global",
"panic",
"use-local-sdk" # enable build from source
# ...
]
Example code same as above.
Build with FLIPPER_FW_SRC_PATH=~/path/to/flipperzero-firmware/ cargo +nightly build --target=thumbv7em-none-eabihf
Also check out instructions for examples.
Build bindings from source with auto- clone remote repository
Needed:
- Rust toolchain (
nightly
channel) - target
thumbv7em-none-eabihf
libclang
for bindgen- Env var
FLIPPER_REPO_BRANCH
with name of branch for the firmware repository (optional) - Env var
FLIPPER_REPO_REV
with name of tag/revision for the firmware repository (optional) - Env var
FLIPPER_REPO_CLONE_PATH
points to directory where the clone should be placed (optional)
Example code same as above, but using use-remote-sdk
instead of use-local-sdk
.
crate manifest:
[dependencies.flipper0-sys]
version = "*"
default-features = false # disable prebuild
features = [
# same as above
"use-remote-sdk" # enable build from source
]
Build with specified place:
FLIPPER_REPO_CLONE_PATH=/abs/path/ \
cargo +nightly build --target=thumbv7em-none-eabihf
And/or with specified branch:
FLIPPER_REPO_BRANCH=release \
cargo +nightly build --target=thumbv7em-none-eabihf
And/or with specified tag or revision:
FLIPPER_REPO_REV="0.70.1" \
cargo +nightly build --target=thumbv7em-none-eabihf
Note:
FLIPPER_REPO_CLONE_PATH
there used instead ofFLIPPER_FW_SRC_PATH
- By default
FLIPPER_REPO_CLONE_PATH
points to$OUT_DIR/sdk
- Without specified branch or rev will be checked out head of default branch.
Build Configuration
Environment variables:
Feature | Required | Description | Use with feature |
---|---|---|---|
FLIPPER_FW_SRC_PATH |
required | Needed to build from source in local working copy of firmware repo, points to root of the repo. | use-local-sdk |
ARM_TOOLCHAIN |
optional | If omitted build-script will search it in the working copy of the firmware repo. Typically should points to "arm-none-eabi" directory. | use-local-sdk , use-remote-sdk |
FLIPPER_REPO_REV |
optional | Revision or tag. | use-remote-sdk |
FLIPPER_REPO_BRANCH |
optional | Name of branch. | use-remote-sdk |
FLIPPER_REPO_CLONE_PATH |
optional | Path points to directory where the SDK repository will be cloned. Default is OUT_DIR/flipperzero-firmware . |
use-remote-sdk |
Features:
allocator
: include allocator implementationallocator-global
: default, include global allocator implementationoom-global
: default, out-of-mem handler. Disable it to use you custom handler or#![feature(default_alloc_error_handler)]
.panic
: default, include global panic & OoM handlermacro
: include#[main]
macro for FAP entry point.
Bindings gen customization features:
Can be used with use-local-sdk
or use-remote-sdk
features.
derive-default
derive-eq
derive-copy
derive-hash
derive-ord
derive-partialeq
derive-partialord
derive-debug
- deriveDebug
, enabled by default for debug profile
All of these derive-
features are used for bindgen configuration.
Build methods features:
Feature | Default | Description | Used ENV vars |
---|---|---|---|
prebuild |
+ | use pre-generated bindings | |
use-local-sdk |
+ | look at FLIPPER_FW_SRC_PATH , build from source |
FLIPPER_FW_SRC_PATH (required), ARM_TOOLCHAIN (optional) |
use-remote-sdk |
- | clone remote git repo, initial setup with fbt, then build from source. | FLIPPER_REPO_REV , FLIPPER_REPO_BRANCH , FLIPPER_REPO_CLONE_PATH , ARM_TOOLCHAIN (all vars optional) |
prebuild
is default feature just for ability to build crate out-of-the-box.
Other documentation useful for development: