QEMU Example

This tutorial will use a Docker container to walk you through building a Yocto image with the Memfault SDK. This image is based on Poky, Yocto's reference distribution.

If you already have your own Yocto-based distribution, we recommend following our integration guide to learn how to add the Memfault SDK.

Build and Run Linux with Memfault SDK

Create a Memfault Project

Go to app.memfault.com and from the "Select a Project" dropdown, click on "Create Project". Once you're done, you can find a Project Key, referenced as YOUR_PROJECT_KEY in this document, in the Project settings page.

Checkout the Memfault Linux SDK

Checkout the Memfault Linux SDK on your computer.

$ git clone https://github.com/memfault/memfault-linux-sdk

The instructions on this guide are compatible with Linux and macOS (Intel and Apple Silicon). Windows users should be able to follow along with minimal adjustments.

Create a Docker container to build with Yocto

We provide a Dockerfile and a run.sh script to create a container.

$ cd /path/to/memfault-linux-sdk/docker
$ MEMFAULT_PROJECT_KEY=<YOUR_PROJECT_KEY> ./run.sh -b

Build your Yocto-based image

This project is configured to build an image for the arm64 architecture on a QEMU (emulated) machine.

To build the image, run:

$ bitbake memfault-image

This will take a long time the first time. Yocto will cache compilation results and future builds will be much faster. We use named Docker volumes to persist source code and build artifacts beyond the container lifetime.

tip

If Docker seems to hang for a long time (build output not updating, CPU usage low) you may have run out of available space allocated to Docker. Check the Docker console for limits on system resources.

Run the image with QEMU

To start QEMU and run the image you have just built, we provide a convenient shortcut:

$ q # Run image in QEMU
// Linux boots

login: root

tip

The q shortcut executes our own runqemu.py which is very similar to runqemu qemuarm64 slirp nographic in newer Yocto distributions.

We maintain compatibility with older versions of Yocto in which runqemu did not support the dual-copy SWUpdate setup that we use here. This is why we provide our own.

Inspect the integration

Login as root and enable data-collection (disabled by default).

$ memfaultctl enable-data-collection

You can now use memfaultctl to generate events on the device. They will appear in your Dashboard.

$ memfaultctl trigger-coredump
$ memfaultctl write-attributes QUICK_START=COMPLETE
$ memfaultctl reboot --reason 4 # Reboot with "Low-Battery Reason"
$ memfaultctl sync

warning

memfaultctl sync is not intended to be used in production. Here we use it to immediately send the events triggered on the QEMU device to Memfault without needing to wait for memfaultd's periodic upload interval.

Next steps

For more information on how this Docker instance is setup, refer to our README in the meta-memfault-example.

To add Memfault SDK to your own Yocto distribution, read our integration guide.