OpenThread Rust API

[darconeous]

Hi.

I wrote a fairly well-thought-out safe async Rust wrapper around the OpenThread API for Fuchsia, and it should in theory port well to other operating systems.

Just wanted to point it out in case there were some useful design patterns.

https://fuchsia-docs.firebaseapp.com/rust/openthread/ot/index.html

What you would do is implement the Platform trait and pass that in when you initialize the ot::Instance. For example, the Fuchsia platform used this crate. You can then create a TaskletStream (src) and handle that however you see best in your async design paradigm. It is written in such a way that you can wrap the ot::Instance either directly in a mutex or in a struct which is protected by a mutex (as long as that class implements AsRef<ot::Instance>).

I spent years working on it. I'd like to think it is well thought-out, but never got around to having a formal release while I was at Google. All of the code is BSD-licensed.

The code that used this on Fuchsia was lowpan-ot-driver. You can see here where we initialize OpenThread with a async sink and stream for Spinel frames.

[ivmarkov]

Thanks a lot for pointing this out!

Well, what can I say - if we knew about this codebase earlier, things could've been different now.
(I guess that's one reason to publish early on crates.io - extra visibility; note to myself - we should do this right after defmt-ing the codebase.)

Regardless, the Fuchsia OT Rust wrappers seem fairly complete, so that would be a great source for inspiration, figuring out how things work, and - ahem - maybe copy-paste (have to figure out what that means w.r.t. our (typical Rust) Apache+MIT dual license).

[ivmarkov]

A few notes on the design of our own wrappers. Would appreciate feedback especially if you spot something fishy:

• Doesn't strive to wrap the complete OT API. The primary reason why these wrappers exist is to make it possible to run rs-matter on the Thread radio of certain MCUs. The OT API surface seems fairly large, and wrapping it would've been (a) a multi-year effort just like yours, and then (b) YAGNI; perhaps we can evolve the API over time, and then there's always the backdoor of calling the unsafe bindgen bindings (openthread re-exports openthread-sys as openthread::sys; need to to provide the user an unsafe access to the otInstance raw pointer and a few other internal mechanics, so that calling into OpenThread C is possible)
• Obiously no_std and no-alloc; looking at the Fuchsia wrappers, they seem to be such as well (I mean, modulo replacing std:: with core::)
• It has a bit of an embedded-MCU focus, so it is opinionated here and there. For example:
  • All futures are !Send and the OpenThread type is !Send as well, which simplifies quite a few things for us
  • The "otPlatform" is reduced to only three traits that the user needs to care about / implement:
    • Radio - a 802154 radio capable of receiving and transmitting 802154 PSDUs; MAC offloading support is optional and can be emulated in software by our wrappers (a bit work in progress though)
    • Settings - obvious what it is
    • RngCore+CryptoRng - also obvious
• (For now) no ambitions to support OT's "multi-instance" mode; also, no ambitions for Thread BR, RCP, NCP

And this is a bit where it gets tricky, and where we might have hidden bugs or even architectural issues:

• It uses a bit of a weird-at-first-sight pattern (Ot*Resources) that is kind of popular in the Embassy community
• The pattern needs a lot of unsafe initialization code and core::mem::transmutes so as to erase certain lifetimes, but as a result, what we get is:
  • These resources structures can be emplaced very efficiently at their final location, as they are initially constructed as a bunch of MaybeUninits (i.e. no risk of stack blowup by rustc emitting code that allocates the structure first on stack and only then moves to .bss or wherever - big problem with MCUs)
  • We can expose a public API that does not need pinning
  • The API is supposed to be safe, including in the presence of core::mem::forget-ing the OpenThread instance (drop fns don't run). That is, putting aside OpenThread::scan is not core::mem::forget safe #25 for now

[nagisa]

also, no ambitions for Thread BR, RCP, NCP

Does that hold for the -sys bindings as well? For most users, I believe, that would be sufficient enough to have just those as an escape hatch, but from what I can tell after staring at openthread for an extended weekend is that most of the functionality is conditionally compiled and -sys does not really expose easy way to modify the conditionals (in fact – it distributing a prebuilt library makes it ever so slightly more difficult to tune exact configuration.)

[ivmarkov]

also, no ambitions for Thread BR, RCP, NCP

Does that hold for the -sys bindings as well? For most users, I believe, that would be sufficient enough to have just those as an escape hatch, but from what I can tell after staring at openthread for an extended weekend is that most of the functionality is conditionally compiled and -sys does not really expose easy way to modify the conditionals (in fact – it distributing a prebuilt library makes it ever so slightly more difficult to tune exact configuration.)

Besides distributing a pre-built library, the crate allows for on-the-fly builds, so if you need br, rcp or ncp you can PR cargo features that enable some or all of these and then I don't see why we should not be accepting such a PR.

[ivmarkov]

Would be interested nevertheless to know why you would need NCP or RCP though. My hope was that the Radio trait would provide a better metaphor where if your radio is on another chip, you could implement a radio proxy (similar to ProxyRadio) except doing serde of the ieee802154 frames in an all-Rust native way using postcard or similar.

[nagisa]

That what I was hoping to do too and was implementing exactly that – it seemed obvious to me to just shuttle ieee802154 around! But then I found that the ecosystem expects pretty well established setups (i.e. the NCP model with OT MAC handled on the radio device) and protocols (Spinel over HDLC/I₂C) and its a pain to do anything else. Implementing HDLC is perhaps not too onerous but Spinel is pretty deeply baked into openthread to the point where manually re-implementing it is not only a chore but is borderline impossible (in part because doing so would require dropping down to writing C++, at which point why not just use what's already there.)

[ivmarkov]

That what I was hoping to do too and was implementing exactly that – it seemed obvious to me to just shuttle ieee802154 around!

I'm not sure I follow your concerns. Perhaps I'm naive. :)
Let's take the RCP model as it is simpler than NCP, and more importantly - I think RCP IS the perfect match for our Radio trait.

You just need to serde ieee802114 frames over SPI/UART/whatever (I2C might be too slow!). Whether you use postcard or just a "roll-your-own" serde is not so important BTW.

Sure, you might need to offload the MAC capabilities to the radio itself, but this is anyway a requirement already now (Radio trait does require TX/RX ack as well as elementary MAC-based filtering by pan ID / ext PAN ID etc.), and if your radio does not have these, you have to anyway wrap it with the MacRadio wrapper, that works on the other side of the wire, in a close proximity to the antenna / on the same MCU where the ieee802154 radio is. And... most radios have these capabilities anyway.

But then I found that the ecosystem expects pretty well established setups (i.e. the NCP model with OT MAC handled on the radio device) and protocols (Spinel over HDLC/I₂C) and its a pain to do anything else.

Also not following. What is established here? All of these things (spinel, etc. etc.) are purely openthread "C" API / library notions. All the vendors do provide however is a simple (though a bit MAC-filtering-capable) ieee802154 radio, which knows nothing about "openthread" anyway. Or am I wrong?

[ivmarkov]

Perhaps it would be easier if you mention concrete ieee802154 vendors, concrete MCUs you have in mind, and what is the problem there. Then I probably understand.

Also and perhaps that's crucial: what stack you plan to use on the chip which runs the radio? Rust or something else?

[nagisa]

Let's take the RCP model as it is simpler than NCP, and more importantly - I think RCP IS the perfect match for our Radio trait.

Oh yeah, I was thinking of RCP rather than NCP. Got my terms mixed up.

Also not following. What is established here? All of these things (spinel, etc. etc.) are purely openthread "C" API / library notions. All the vendors do provide however is a simple (though a bit MAC-filtering-capable) ieee802154 radio, which knows nothing about "openthread" anyway. Or am I wrong?

Tools on the host side using or interacting with openthread have expectations to the effect of requiring spinel/hdlc. ot-br-posix comes to mind as an immediate example. And while spinel is indeed orthogonal to Thread itself, it is appears to be pretty integral to the openthread stack, or at least some applications of it (such as RCP). Spinel in these applications acts more like a remote procedure call mechanism rather than just a pure data channel. Some commands do indeed make it through OT and into platform bindings, while others get handled entirely internally within openthread. And while I haven't attempted to replicate this functionality with openthread's public C API, I suspect that before long there would be some facet of behaviour that wouldn't be easy or possible to replicate with just the public C API of openthread. Which means using its Spinel logic.

---

Also and perhaps that's crucial: what stack you plan to use on the chip which runs the radio? Rust or something else?

I've been implementing an RCP in Rust on an esp32c6. I already had a MVP passing around raw ieee802154 radio data, but that turned out to be onerous to integrate with e.g. ot-br-posix on the host side. Hence my interest in getting the RCP-relevant Spinel/HDLC functionality and interface exposed in at least openthread-sys.

(Yes, I know I could just use esp-idf's example, but don't wanna :))

[ivmarkov]

OK so your use case is a Border Router on ARM or similar hardware (or maybe even a PC) with openthread-over-tun or something and then an ieee802154 "dongle" using the c6 or the h2 MCU?

Where do you plan to use Rust? If just on the "dongle", I don't think it makes much sense? Why bother? I would actually just flash the esp-idf example and wouldn forget about the dongle after that?

If you plan to use Rust on the host, then you rather need the Border Router functionality exposed, and you don't even need a pre-built library as this is not an MCU but Linux or embedded Linux or suchlike.

[darconeous]

Random side comment: I am the guy who came up with Spinel originally. I also designed the SPI protocol. Kind of amusing to see it all still being used. I guess it is well-baked-in at this point.

[jdswensen]

If it is of any interest, I did experiment with writing a Spinel implementation in Rust over a year ago. It was mostly a proof of concept to learn more about the protocol. I started working on a more full implementation with connection management but got busy at work and haven't really picked it back up. I was able to use a FTD (no CLI) to inspect frames comping from the device after it had been configured to join a network.

[darconeous]

@jdswensen : I wrote a well-tested async-rust-based Spinel implementation for Fuchsia. It should be in the tree linked from my original post, but if you like I can direct you to it (traveling at the moment). It would likely be easy/straightforward to port to other platforms.