Auteur/autrice : julien

It is finally here! After 4 months of development, the first release of ZigRouille is out. The following post will go through what we have done so far, and what still has to be done.

Overview

ZigRouille’s goal is to create a safe Rust interface to the ZBOSS stack on nRF52840 chips. ZBOSS is a proprietary library that integrates a ZigBee communications API. The ZigRouille Rust library has to be split in two parts to connect to this API:

• zboss-sys, which links the ZBOSS binary and provides bindings to the API entry points.
• zboss-rs, a higher-level abstraction library to wrap the raw bindings into a new safe API, as well as a Rust implementation of the ZBOSS hardware interface.

To test those libraries, we use a binary crate test-env that also provides a quick-start configuration and several examples using ZigRouille.

Features

The main part of the project resides in zboss-rs: it has a duty to enforce Rust safety rules on the unsafe C API.

Initialization

We enforce at compile time that we have a unique initialization of the ZBOSS stack, and that this stack is configured and started before any other ZBOSS-related code runs.

Memory

The ZBOSS stack holds a buffer pool to perform all ZigBee operations that require memory storage. Those buffers can be requested by the user, or given as a function returns. The buffers do not have an explicit structure in ZBOSS, so we had to structure them explicitly when we use them in the Rust world. Also, the buffers are sometimes required to be explicitly freed by the user, so we enforce that too.

Scheduler

ZBOSS uses serialized callbacks to implement an internal multitasking. We wanted to allow the user to have more variety in the callback types they can use, so we added an extra level of indirection to keep track of the callback requests and responses in the Rust world.

Signals

ZBOSS uses a system of signals to inform the user of some events and allow them to react accordingly. We structured it so that they only have to register individual signal handlers, and implemented a default signal handler (similar to the one Nordic uses).

ZigBee Procedures

Each ZigBee procedure implemented in ZBOSS has its own entry point, so we have to implement them one by one. Therefore, only a small subset off all procedures are currently implemented. We wanted to achieve at least simple light automation for the first release, the other procedures can be added later.

OSIF

The OSIF contains entry points to hardware or OS functions from ZBOSS. For example, the OSIF provides hardware initialization functions called during ZBOSS initialization, or even the code needed to put the device into sleep mode. This OSIF also relies on the radio driver provided by Nordic for the nRF52840 (everything else is written in Rust), that should be linked when building zboss-rs.

What’s next?

The 0.1.0 release is fully functional. However, there still are a lot of features present in ZBOSS that are not yet interfaced with our implementation. In particular, we cannot keep track of some (optional) callbacks given to ZBOSS through special entry points, and we do not handle ZCL callbacks yet. Therefore, it is currently not possible to implement server ZCL clusters e.g. Level Control for a light bulb. Also, ZDO information cannot be retrieved by the user in signal callbacks, a wrapper has to be implemented for that. We would gladly welcome any upcoming contribution! ?

Pour réaliser notre projet nous devons pouvoir nous interfacer en Rust avec la bibliothèque C ZBoss. Le C étant beaucoup plus dangereux que le Rust, et différent, de nombreuses précautions sont à prendre. Cet article recense les outils et les bonnes pratiques à suivre pour interagir avec du code étranger dans notre projet.

Caisses intéressantes

cty

Fournit les types C de base (on ne peut pas utiliser libc pour notre cible).

On a les correspondances suivantes :

C	cty	Rust (ARM)
char	c_char	i8
signed char	c_schar	i8
unsigned char	c_uchar	u8
short	c_short	i16
unsigned short	c_ushort	u16
int	c_int	i32
unsigned (int)	c_uint	u32
long	c_long	i32
unsigned long	c_ulong	u32
long long	c_longlong	i64
unsigned long long	c_ulonglong	u64
float	c_float	f32
double	c_double	f64
X	X	bool
T *	X	*mut T
const T *	X	*const T
void *	*mut c_void	*mut c_void
const void *	*const c_void	*const c_void
size_t	size_t	usize
ptrdiff_t	ptrdiff_t	isize

Bien entendu les types de taille fixe de stdint peuvent être utilisés :

C (stdint.h)	cty	Rust
int8_t	int8_t	i8
uint8_t	uint8_t	u8
int16_t	int16_t	i16
uint16_t	uint16_t	u16
uint32_t	uint32_t	u32
int32_t	int32_t	i32
int64_t	int64_t	i64
uint64_t	uint64_t	u64

cstr_core

Les chaînes de caractères en Rust ne sont pas construites de la même manière qu’en C : il n’y a pas de caractère nul à la fin, et les caractères nuls sont admis au sein de la chaîne.

cstr_core fourni CStr (et CString si l’allocation est activée) comme chaîne se comportant comme en C.

rust-bindgen

A partir des entêtes C (éventuellement C++) d’une bibliothèque, génère les prototypes et les structures de données à l’interface adaptés à Rust.

Note : la caisse peut être utilisée pour la génération (build script, donc utilisé comme dépendance dans Cargo sous [build.dependencies]), puis enlevée des dépendances pour alléger le projet, ou encore utilisée dans une caisse à part du projet dédiée aux bindings.

Attributs utiles

#[link(name = « ext_library »)]

Indique au compilateur que les fonctions d’un bloc extern sont à lier à la bibliothèque donnée.

Exemple :

#[link(name = "git2")]
extern "C" {
    pub fn git_libgit2_init() -> c_int;
    pub fn git_libgit2_shutdown() -> c_int;

    . . .

}

#[repr(C)]

Force l’agencement en mémoire d’une structure à suivre les règles du C (ordre des champs, espacement entre les champs, alignement)

#[repr(C)]
pub struct git_error {
    pub message: *const c_char,
    pub klass: c_int,
}

#repr(align(n))

Force l’alignement sur n bytes, n doit être une puissance de 2.

#[no_mangle]

Empêche le mangling par défaut du symbole, utile pour aider le linker à retrouver les symboles en multi-langage.

Techniques et bonnes pratiques

Unsafe et contrat

Lorsqu’une fonction ou un trait sont déclarés comme unsafe il est impératif de documenter le contrat d’utilisation, c’est-à-dire de préciser le cadre d’utilisation pour ne pas avoir de comportement indéfini.

Exemple dans la bibliothèque standard : la fonction Vec::get_unchecked :

pub unsafe fn get_unchecked<I>(&self, index: I) -> &I::Output
    where
        I: SliceIndex<Self>,
    {
        // SAFETY: the caller must uphold most of the safety requirements for `get_unchecked`;
        // the slice is dereferencable because `self` is a safe reference.
        // The returned pointer is safe because impls of `SliceIndex` have to guarantee that it is.
        unsafe { &*index.get_unchecked(self) }
    }

Ce contrat est essentiel car s’il est violé, cela peut introduire des comportements indéfinis dans du code Rust supposé sûr.

Utiliser une variable globale externe en Rust

Utiliser static dans le bloc extern lié à la bibliothèque externe :

#[link(name = "readline")]
extern {
    static rl_readline_version: libc::c_int;
}

Utiliser une fonction C en Rust

On déclare la fonction dans un bloc extern "C". Tous les appels à celle-ci sont nécessairement unsafe.

La déclaration en C :

// header.h
int git_libgit2_init();

Le code Rust :

// main.rs
extern "C" {
    pub fn git_libgit2_init() -> c_int;
}

fn main() {
    unsafe {
        git_libgit2_init();
    };
}

Fonctions variadiques

On peut utiliser les fonctions variadiques du C en Rust :

extern {
    fn foo(x: i32, ...);
}

fn main() {
    unsafe {
        foo(10, 20, 30, 40, 50);
    }
}

Utiliser une fonction Rust en C

On utilise #[no_mangle] et extern "C" comme vu précédemment.

#[no_mangle]
pub extern "C" fn magic_number() -> c_int {
    42
}

Et on ajoute bien évidemment du côté C :

extern int magic_number();

Panique

A l’extérieur de Rust, les paniques causent un comportement indéfini, il faut donc les éviter. S’il faut quand même paniquer, utiliser catch_unwind.

Pointeur nul

Beaucoup de types Rust ne peuvent pas être nuls, notamment les références et les pointeurs de fonction. Ce n’est en revanche pas le cas en C. Le langage Rust donne une approche simple pour s’interfacer avec le C dans cette situation : pour faire simple, utiliser une Option. La structure sera bien optimisée avec None correspondant à la valeur nulle et Some correspondant à la valeur non-nulle.

C	Rust
int (*)(int)	Option<extern "C" fn(c_int) -> c_int>
data_t *	Option<*mut data_t>

Libération de la mémoire

On utilise le trait Drop pour appeler les fonctions étrangères qui conviennent à la libération de la mémoire.

Exemple :

impl Drop for Repository {
    fn drop(&mut self) {
        unsafe {
            raw::git_repository_free(self.raw);
        }
    }
}

Structure opaque

Si les entêtes en C décrivent un type opaque :

typedef struct Foo Foo;

Ou bien en argument de fonction :

void bar(void *foo);

Alors on utilise dans le code Rust :

#[repr(C)] pub struct Foo { _private: [u8; 0] }

extern "C" {
    pub fn bar(arg: *mut Foo);
}

On manipulera donc uniquement ces structures avec des pointeurs bruts.

Le matériel

Nous utilisons deux kits de développement fournis par Nordic :

• La carte de développement nRF52840
• Le dongle nRF52840

Le nRF52840 (référence) est construit à partir d’un Cortex-M4, et implémente plusieurs protocoles de communication, notamment ZigBee qui nous intéresse dans notre projet.

Les outils de programmation

Les workshop de Ferrous Systems fournissent des outils de développement en Rust pour compiler les programmes, programmer la carte, recevoir du logging, etc.

L’essentiel

probe-run

C’est l’utilitaire qu’on utilisera le plus : construit l’exécutable (cargo-run), programme la carte en utilisant la sonde JTAG (probe-rs), et récupère les log et les traces de la pile d’exécution via le protocole RTT.

nrfutil

Utilitaire fourni par Nordic, il permet notamment de programmer le dongle (qui ne possède pas de sonde intégrée).

Autres utilitaires

cargo-flash

Permet de programmer la carte en utilisant la sonde JTAG de la carte de développement (utilise probe-rs).

cargo-embed

Pour visualiser les log via le protocole RTT. (peut servir aussi à programmer la carte grâce à probe-rs)

cargo-binutils

Fournit nm, objdump, objcopy, etc.

cargo-bloat

Analyse l’espace utilisé dans un fichier ELF (ou équivalent).

nrf-recover

Pour déverrouiller la flash si nécessaire.

Projet de référence

(voir https://embedded-trainings.ferrous-systems.com/from-scratch.html)

Pour commencer un nouveau projet en Rust sur la cible nRF52840, on utilise le projet de référence fourni ici : https://github.com/rust-embedded/cortex-m-quickstart en paramétrant pour un Cortex-M4.

Pour obtenir un HAL pour la carte, on utilise nrf52840-hal.

Si l’on veut allouer des structures de données sur la pile, on utilise heapless.

On peut ensuite utiliser rtt-target dans le projet pour générer des log qui transitent par la sonde.

Si nécessaire, on utilisera aussi le système d’exploitation RTIC.

Notre projet de référence se trouve sur notre dépôt ici : quickstart_project

Et c’est parti ! …ou pas. Avant de commencer à coder quoi que ce soit, quelques règles s’imposent.

Organisation

Même si Sylvain et moi ne sommes que deux, nous nous sommes mis d’accord sur quelques règles pour ne pas nous marcher sur les pieds.

Git, Gitlab, etc.

Première règle absolue : ce qui est sur main est considéré comme étant du code en production. Cela implique que tout code en cours de développement est mis sur une branche à part tant qu’il n’est pas prêt pour la mise en production. On essaiera de faire idéalement une branche par fonctionnalité développée.

Lorsqu’une fonctionnalité est prête à être fusionnée dans main, on fera une merge request dans Gitlab afin d’approuver à deux la fusion.

Concernant les messages de commit, on utilisera les conventions données par git. Les messages sont en anglais et à l’impératif, leur titre ne doit pas faire plus de 50 caractères et le corps doit faire au plus 80 caractères de large.

Suivi de l’avancement

Les issues de Gitlab permettent de discuter sur des bugs ou des fonctionnalités, et peuvent être visualisées comme un kanban. On utilisera donc celles-ci pour suivre le développement des fonctionnalités.

Licence

Comme imposé pour notre projet, tout le code que nous écrirons sera sous licence libre duale Apache License 2.0 / MIT.

---

En résumé

• branche main = production
• Les fonctionnalités sont isolées sur des branches à part
• On utilise les pull requests pour fusionner avec main
• Les messages de commit :
  • en anglais
  • titre à l’impératif
  • titre <= 50 caractères
  • corps : lignes de moins de 80 caractères
• issues Gitlab pour le suivi
• Licence Apache License 2.0 / MIT

C’est bon on peut y aller ?

Il faut d’abord savoir où l’on va ! Avant de pouvoir développer sur notre carte développement nrf52840 une interface ZBOSS en Rust pour communiquer en ZigBee, il faut se former à chacun de ces éléments. Notre démarche initiale est la suivante :

1. Beginner workshop de Ferrous Systems
2. Advanced workshop de Ferrous Systems
3. Etudier le fonctionnement de ZigBee et de 802.15.4
4. Prendre en main l’interface ZigBee/ZBOSS de Nordic : https://infocenter.nordicsemi.com/index.jsp?topic=%2Fstruct_sdk%2Fstruct%2Fsdk_thread_zigbee_latest.html&cp=7_3
   • ZBOSS : https://infocenter.nordicsemi.com/index.jsp?topic=%2Fsdk_tz_v4.1.0%2Fgroup__ll.html&cp=7_3_5_1_9
5. Réaliser les bindings Rust de ZBOSS

On peut envisager si le temps nous le permet d’aller plus loin :

• Faire une surcouche haut niveau si l’API ZBOSS est peu pratique
• Réfléchir à des applications IoT, domotique, etc.
• Utilisation conjointe de ZigBee et du Bluetooth

Nous avons commencé par prendre en main la carte de développement en réalisant les workshops organisés par Ferrous Systems, mais ça ce sera pour une prochaine fois…