Categories
IoT Zephyr

5 Tips to Make the Most of Zephyr Documentation

It’s already feature freeze day for Zephyr 4.0, and it’s been two months since I last posted a Zephyr Weekly Update. Oops! Personal life got in the way, a baby girl joined our family since then. So, there’s my excuse! 🙂

Since it wouldn’t do justice to any of the features introduced over the past few months by cramming them all into one post, I decided to focus on some recent improvements to the Zephyr documentation that you ought to know about.

New board catalog

There are well over 600 boards supported in Zephyr, and until very recently we didn’t really provide an easy way for someone to easily get a sense of which boards were available for a given architecture or SoC family, or from a given vendor. Instead, one would be served with a ginormous “flat” list of hundreds of boards that was really hard to navigate.

With the new board catalog, you can now easily filter boards according to various criteria, and narrow down the list of 620+ boards to only the boards that you care about in just seconds.

And more is coming! This catalog will soon also allow you to do something that’s even more useful when prototyping a new project which is filtering by supported hardware capabilities (think: “I am looking for a board with a display, a Bluetooth chip, and from vendor Foo, what do you have in stock for me, Zephyr?”).

Towards Zephyrpedia? 🙂

You may have noticed that the documentation page for -most- boards recently changed.


That new card on the side of the page, similar to what you would find on Wikipedia, is a first step towards trying to provide more structure and uniformity to the documentation of the various boards supported in Zephyr and, more importantly, to make sure that every piece of information that can automatically be deduced from things like Devicetree, or the board hardware model, is used to generate the documentation.

The intent is to make it way less likely that things like the Supported Features section of a board’s doc page get outdated, since they will be generated from a single source of truth.

Finding the right code sample

We have nearly 500 different code samples so, as you might have experienced, it can sometimes be hard to find the right sample for your needs.

Somewhat similar to the board catalog, you can now quickly search for samples right from the samples index page. As a lot of effort was spent carefully reviewing the description of the samples, and making sure they contain the right keywords in them, you should be able to find what you’re looking for much more easily.

Try it for yourself, whether you care about mqtt, audio, servo, battery, or whatever else, you will hopefully find at least one sample that will help you get going!

What’s also new is that the README for each code sample now includes a button that can directly take you to the source code of said sample on Github!

C API tooltips

You may have noticed that the documentation of Zephyr’s C API is not “inlined” in the main documentation page anymore, and you may now refer directly to the Doxygen documentation to access the reference documentation of the various APIs.

However, in many cases you probably won’t have to leave the main Zephyr documentation since everytime an API is mentioned in the documentation, you can hover over it to get a tooltip which will directly show you the full Doxygen documentation of that API.

Where’s the driver for that compatible?

Often times, when adding or editing a node in your Devicetree, looking at the documentation of the binding properties is not enough to understand how the actual driver matching the node’s compatible makes use of the properties, and what behavior to expect.

From the Devicetree bindings documentation page, you may now click on the compatible you’re interested in and, alongside the documentation of the various binding properties, you can now actually go directly to the matching driver’s source code to see how it’s implemented. Handy, eh?


I am sure there are a lot more tips I could share, but I am also quite certain there are things you would like to see implemented in the documentation so please feel free to join the #documentation channel on Discord to get the conversation going!


As always, I very much welcome your thoughts and feedback in the comments below!

If you enjoyed this article, don’t forget to subscribe to this blog to be notified of upcoming publications! And of course, you can also always find me on Twitter and Mastodon.

Catch up on all previous issues of the Zephyr Weekly Update:

Categories
IoT Zephyr

Zephyr Weekly Update – Aug. 23, 2024

As there were quite a few large and significant features that landed since the last time I posted, I will use a slightly different approach this week and won’t be going in details through all the new boards, drivers, or SoCs, but will rather spend time on presenting what these new features are and how they can be useful to you.

Manage your Zephyr SDK using West

I can’t believe we’ve lived all this years without such a command, but I am really glad it’s now available! While you typically don’t (re-)install the Zephyr SDK everyday, this is a task which can require quite a bit of work and be error-prone. And this is even more true for Zephyr newcomers, of course.

With the new west sdk command, one can now easily manage the download and installation of the Zephyr SDK. In most cases, it will just work™ and will, for example, automatically look for the latest version of the SDK.

The Zephyr Getting Started Guide should be updated shortly to take advantage of this new cool tool, but in the meantime I really encourage you to basically have a look at the various options documented via west sdk --help so that you keep the tool in mind for next time you need to tinker with your Zephyr SDK!

New performance profiling subsytem

We had two Zephyr Tech Talks in the recent past where we discussed tracing and profiling (check them out!) and the question that was asked first on both occasions was: what’s the performance impact on my application going to be if I enable tracing/profiling?

It is an important question since in most cases you don’t want the performance overhead to be such that it will completely change how your application behaves, for example due to tasks taking longer to do their job and causing changes in the scheduling.

A new profiling subsystem has recently been introduced with a first implementation of a very lightweight profiling mechanism that samples the stack trace at regular intervals.

Once a given configurable period has elapsed, you are able to retrieve the captured raw information, run it through a Python script, and then directly feed it into FlameGraph to get a visual representation of what your application has been busy doing during that time.

This provides you with a quick overview of what’s going on, and allows you to potentially spot unexpected bottlenecks, or a stack getting dangerously close to overflowing.

HTTP Server sample gets some nice improvements

The HTTP server sample has some new interesting features worth checking out, as it now serves new resources that demonstrates something closer to what you may be interested in doing for a real-life scenario.

    More specifically the sample now serves a “home page” that’s much more useful as before, as it exercises HTTP resource handlers that are doing more than the simple “echo” service from before. Namely, there is now:

    • a /led resource that can be POSTed to and will take JSON commands allowing to toggle an LED on or off. This is also a great way to get some concrete example of how JSON can be used in combination with the HTTP server library, as it’s definitely a common serialization format 🙂
    • an improved WebSocket showcase since the web page can now show network traffic statistics in real-time, directly streamed from the Zephyr device to the browser.
    • a new /uptime endpoint that serves the device uptime dynamically.

    Give the code sample a try, I am pretty confident this will give you some inspiration 🙂


    A big thank you to the 23 individuals who had their first pull request accepted since the last post 💙 🙌: @maxdog988, @lucien-nxp, @thenguyenyf, @Stan-Corellium, @Yagoor, @tot0rokr, @Terezvent, @johankraft, @epc-ake, @deGerard, @marek14, @cyberjupiter, @wearyzen, @xiaolusu, @bianik, @zin-HXQ, @haduongquang, @krzysztofgawrys, @KushnerovMikhail, @tunguyen4585, @GrygiriiS, @esoutham-lvt, and @morihisa-momona.

    As always, I very much welcome your thoughts and feedback in the comments below!

    If you enjoyed this article, don’t forget to subscribe to this blog to be notified of upcoming publications! And of course, you can also always find me on Twitter and Mastodon.

    Catch up on all previous issues of the Zephyr Weekly Update:

    Categories
    IoT Zephyr

    Zephyr Weekly Update – Feeling a disturbance in the Force

    We are just a few days away from hitting 100,000 (!) commits on the main Zephyr repository, and things are not really slowing down despite the summer holidays 🙂 Let’s dive right in!

    New Haptics driver class

    It is common for interactive devices to provide haptic feedback to the user. For example, pressing widgets on a touch screen may trigger gentle vibrations while a stronger vibration may indicate that the action was not successful. Well, as of this week, Zephyr supports haptic feedback devices through a new haptics driver class!

    An IC providing haptic feedback functionality is typically hooked up to a tiny motor that will vibrate when a signal is sent to it. The actual vibration pattern can be controlled in several ways: directly feeding the IC with a PWM or analogue signal, using built-in “melodies” available from the chip’s ROM (ex. “strong click”, “short double click”, etc.), etc.

    The new haptics driver class provides a common API for starting/stopping vibrations, and for now most of the actual configuration is done through hardware-specific API. (PR #76343)

    Texas Instruments DRV2605 is the only driver implementing this API for now, but let’s hope we’ll get more in the near future.

    I’ll try to prepare a short demo of this new feature for the next blog post, but you may check out this code sample in the meantime.

    A practical State Machine Framework example

    I have mentioned Zephyr’s State Machine Framework quite a bit in the past, and I am happy to see that more and more subsystems are either transitioning to it, or considering doing so. State machines are something you definitely don’t want to get wrong, and using a proven framework can really help with making your code easier to read, test, and maintain over time.

    We have a new very cool code sample that implements a calculator with a fancy LVGL GUI and whose logic is implemented using the State Machine Framework.

    It is really nice to see how to turn a pretty complex state machine into something that can actually be executed and hooked up to a UI. I hope this will inspire folks to look at SMF whenever they’re just about to get lost in switch/case madness 🙂

    (PR #76465)

    SoCs, Boards & Shields

    Support has been added for the following SoCs:

    • Several SoCs from Analog Devices’ DARWIN MAX326xx Series (MAX32662 , MAX32666, MAX32675). (PR #73578, #73560, #73576)
    • FLPR (Fast Lightweight Processor) RISC-V core on nRF54H20 is now supported. (PR #75451)
    • Wi-Fi driver for the NXP RW612 has been added. (PR #76289)

    New boards and shields:

    • The nRF7002 EK is a versatile evaluation kit in the form of an Arduino shield that can be used in Nordic and non-Nordic host boards. (PR #75714)
    • 01space ESP32C3-0.42-OLED. (PR #74964)
    • STM32F405 Core. (PR #74378)

    Drivers

    • New MBOX driver for ESP32. (PR #76301)
    • New DMA driver for MAX32xxx. (PR #76627)

    Miscellaneous

    • Added support for Wi-Fi Device Provisioning Protocol (DPP) via hostap. DPP is a secure, simplified method for connecting devices to a Wi-Fi network without needing to share the network password directly. (PR #73707)
    • A new reset_stats() API has been introduced to allow resetting Wi-Fi usage statistics. (PR #75768)
    • New sample application demonstrating how to use the CoAP client. (PR #76069)
    • LittleFS module has been updated to 2.9.3. (PR #74001)
    • POSIX
      • Added support for _POSIX_THREAD_PRIO_PROTECT. (PR #74386)
      • Implemented readdir_r. (PR#74394)

    A big thank you to the 16 individuals who had their first pull request accepted this week, 💙 🙌: @alexstanoev-nordic, @nngt88, @pyadvichuk, @duynguyenxa, @juliaazziz, @LeoBRIANDSmile, @aa889788, @yiding, @konrad1s, @unsanded, @thales-nascimento, @pblxptr, @LiLongNXP, @Robibobo1, @asingh-GiN, and @00thirdeye00.

    As always, I very much welcome your thoughts and feedback in the comments below!

    If you enjoyed this article, don’t forget to subscribe to this blog to be notified of upcoming publications! And of course, you can also always find me on Twitter and Mastodon.

    Catch up on all previous issues of the Zephyr Weekly Update: