Repository: https://github.com/billvanleeuwen424/ms8607-driver

Background

Device drivers bridge hardware and the operating system. Without a driver, the kernel can't communicate with hardware devices. For the MS8607, the driver needs to:

• Communicate over I2C with two sensor addresses (0x76 for pressure/temp, 0x40 for humidity)

• Read factory calibration data from PROM and validate with CRC

• Convert raw ADC values to pressure (mbar), temperature (°C), and humidity (%RH)

• Expose data through IIO's sysfs interface at /sys/bus/iio/devices/

Hardware Setup

I utilized this pinout diagram from element14 here.

The MS8607 is mounted on an Adafruit breakout board and connected to the BeagleBone Black I2C2 bus:

P9_19 (I2C2_SCL) → SCL
P9_20 (I2C2_SDA) → SDA
P9_3  (3.3V)     → VIN
P9_1  (GND)      → GND

I had the board connected up like so on this very professional breadboard:

Validating I2C Communication

Standard practice is to run i2cdetect first:

sudo i2cdetect -y 2
     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
00:                         -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
70: -- -- -- -- -- -- -- --

Nothing showed up. The MS8607 doesn't respond to i2cdetect probing—it requires specific command sequences. Manual validation with i2cget and i2cset confirmed both sensors were functional

# Test humidity sensor at 0x40
i2cget -y 2 0x40 0xE7
# Output: 0x02

# Test pressure/temp sensor at 0x76
i2cset -y 2 0x76 0x5A
i2ctransfer -y 2 w1@0x76 0x00 r3
# Output: 0x85 0x4f 0x37

Device Tree Configuration

I had to learn a lot about device trees for this project. Again, I recommend Bootlin documentation extremely useful! I utilized this slide deck on Device Tree 101 from Bootlin.

The MS8607 contains two sensors on one chip with different I2C addresses. This presented an architecture choice: write two separate drivers (one per sensor) or a single driver managing both.

Initial Approach

The first device tree had two nodes, both enabled:

ms8607-pt@76 {
    compatible = "te,ms8607-pt";
    reg = <0x76>;
    status = "okay";
};

ms8607-h@40 {
    compatible = "te,ms8607-h";
    reg = <0x40>;
    status = "okay";
};

The Problem

With both nodes at status = "okay", the kernel instantiates I2C devices at both addresses during boot. When the driver tried to create a dummy client for 0x40 using devm_i2c_new_dummy_device(), it failed with -EBUSY (error -16)—the address was already taken.

Solution

Only the primary sensor at 0x76 has status = "okay". The secondary sensor is documented but disabled:

/* Primary - driver binds here */
ms8607@76 {
    compatible = "te,ms8607";
    reg = <0x76>;
    status = "okay";
};

/* Secondary - documented but disabled */
ms8607-h@40 {
    compatible = "te,ms8607-humidity";
    reg = <0x40>;
    status = "disabled";
};

The driver creates the humidity sensor client internally. This exposes all three channels (pressure, temperature, humidity) through a single IIO device.

Driver Implementation

Development Tools

I used Claude Code for parts of this project—parsing datasheet formulas, generating the CI/CD pipeline, and discussing architecture trade-offs. It was useful for accelerating tasks that would normally require reading documentation or trial-and-error. Hardware debugging and sensor validation still required hands-on work with the BeagleBone.

Calibration and CRC Validation

The pressure/temperature sensor stores factory calibration coefficients (C1-C6) in PROM. These coefficients are used in the datasheet's formulas to convert raw ADC values into calibrated pressure and temperature readings. If the coefficients are corrupted, all sensor readings will be wrong.

The driver reads the PROM once during probe and validates the data with a 4-bit CRC:

static int ms8607_load_calibration(struct ms8607_data *data)
{
    int ret;
    u16 prom[8];

    ret = ms8607_read_prom_words(data->client, prom);
    if (ret)
        return ret;

    if (!ms8607_validate_prom_crc(prom)) {
        dev_err(&data->client->dev, "PROM CRC validation failed\n");
        return -EIO;
    }

    memcpy(data->calibration, prom, sizeof(data->calibration));
    data->calibration_valid = true;
    return 0;
}

Sensor Readings

Each sensor requires triggering an ADC conversion, waiting for completion, then reading the result.

Humidity (16-bit):

// Trigger no-hold measurement
i2c_smbus_write_byte(client_h, 0xF5);
msleep(9);  // ADC conversion time

// Read result
adc = i2c_smbus_read_word_data(client_h, 0xE5);

// Convert to 0.01%RH units
humidity = -600 + ((12500 * adc) >> 16);

Pressure (24-bit, requires temperature compensation):

// Trigger temperature conversion
i2c_smbus_write_byte(client, 0x58);
msleep(9);

// Read D2 (raw temperature)
i2c_smbus_write_byte(client, 0x00);
i2c_smbus_read_i2c_block_data(client, 0x00, 3, buf);
D2 = (buf[0] << 16) | (buf[1] << 8) | buf[2];

// Trigger pressure conversion
i2c_smbus_write_byte(client, 0x48);
msleep(9);

// Read D1 (raw pressure)
i2c_smbus_write_byte(client, 0x00);
i2c_smbus_read_i2c_block_data(client, 0x00, 3, buf);
D1 = (buf[0] << 16) | (buf[1] << 8) | buf[2];

// Apply calibration (datasheet formulas)
dT = D2 - (C5 << 8);
TEMP = 2000 + ((dT * C6) >> 23);
OFF = (C2 << 17) + ((C4 * dT) >> 6);
SENS = (C1 << 16) + ((C3 * dT) >> 7);
P = (((D1 * SENS) >> 21) - OFF) >> 15;

IIO Integration

The driver registers three channels:

static const struct iio_chan_spec ms8607_channels[] = {
    {
        .type = IIO_PRESSURE,
        .info_mask_separate = BIT(IIO_CHAN_INFO_RAW) | BIT(IIO_CHAN_INFO_SCALE),
    },
    {
        .type = IIO_TEMP,
        .info_mask_separate = BIT(IIO_CHAN_INFO_RAW) | BIT(IIO_CHAN_INFO_SCALE),
    },
    {
        .type = IIO_HUMIDITYRELATIVE,
        .info_mask_separate = BIT(IIO_CHAN_INFO_RAW) | BIT(IIO_CHAN_INFO_SCALE),
    },
};

Userspace reads from /sys/bus/iio/devices/iio:device0/:

• in_pressure_raw: 97983 → 979.83 mbar

• in_temp_raw: 2073 → 20.73°C

• in_humidityrelative_raw: 3051 → 30.51%RH

Testing

An automated test script handles module loading and sensor validation:

#!/bin/bash
make clean && make
sudo insmod main.ko

# Find IIO device
IIO_DEV=$(find /sys/bus/iio/devices/ -name "*ms8607*")

# Read sensors
echo "Pressure: $(cat $IIO_DEV/in_pressure_raw) (raw)"
echo "Temperature: $(cat $IIO_DEV/in_temp_raw) (raw)"
echo "Humidity: $(cat $IIO_DEV/in_humidityrelative_raw) (raw)"

All three sensors reported valid readings on hardware.

CI/CD Pipeline

GitHub Actions runs static analysis and device tree validation on every push:

• checkpatch: Linux kernel coding style verification

• sparse: Static analyzer for kernel code

• cppcheck: Additional static analysis

• Device tree compilation: Validates overlay syntax

ARM cross-compilation builds run on manual trigger or release tags. The workflow builds vmlinux before modules to ensure proper symbol resolution—building only make modules caused missing symbol errors in modpost.

Platform-Specific Issues

ARM32 Division

The ARM32 kernel doesn't support 64-bit division. This issue showed up during CI cross-compilation—code that built fine on x86 failed with a link error on ARM:

// WRONG - link error on ARM32
s64 temp = 2345;
dev_info(&client->dev, "Temp: %lld°C\n", temp / 100);
// ERROR: "__aeabi_ldivmod" undefined!

Fix: cast to 32-bit before division:

// CORRECT
s64 temp = 2345;
int temp_int = (int)temp;
dev_info(&client->dev, "Temp: %d°C\n", temp_int / 100);

Resources

Hardware & Datasheets:

• MS8607 Datasheet

• Adafruit MS8607 Breakout

• BeagleBone Black Documentation

Linux Kernel Documentation:

• IIO Subsystem

• I2C Subsystem

• Device Tree Usage

Code References:

• MS8607 Driver Repository

• MS5637 Driver (similar sensor)

• BeagleBone Device Tree Overlays

Learning Resources:

• Bootlin Training Materials

• Bootlin Device Tree 101

This project gave me hands-on experience with the driver layer of embedded Linux—something I haven't yet had the chance to work with. Writing a kernel module from scratch meant learning more about device trees, IIO subsystem internals, I2C protocol details, and platform-specific constraints like ARM32 arithmetic limitations.

If you're interested in embedded Linux development, the full source code and documentation are available in the GitHub repository.

Thanks for reading! :)

Intro

AI is all the hype these days. Where I currently work, we are just getting started accepting the world of AI - primarily for log analysis, and use of co-pilot in our editors.

I wanted to try out using an AI agent. I utilize Zed for any personal projects. It has beautiful integration for AI Agents.

To be clear with the reader, I don't fully understand what an 'AI agent' really is. I understand that it can modify your source code files, as well as run terminal commands (this is super cool by the way. will talk more on this later). But outside of this, I don’t know what it means for something to be 'agentic'.

How did it work?

I'm utilizing Gemini for this, not for any particular reason. I started simple, asking the agent to generate me in Rust a simple TCP server which reverses any strings sent to it.

I wanted to run this in Docker, so I asked. It created a docker file, and built the container!

What Amazed Me Most

This AI Agent even helped debug system level issues. It really seemed like it was thinking along with me. Starting out, it bound to 127.0.0.1 (localhost).

let listener = TcpListener::bind("127.0.0.1:8081").unwrap();

This didn’t allow me to connect to the server. I was able to debug this with the agent. It added extra logs to the project, and when it couldn't see those in the log output I provided, it suggested a fix which worked! Instead, we needed to bind to 0.0.0.0 (all interfaces). Wow!

This whole process took maybe 30 minutes. I would humbly say I’m still a beginner with Rust, and this project might have taken me 3-4 times as long to do without this tool.

Outro

As this journey concludes, I can confidently say that venturing into AI-assisted development has been an incredibly rewarding experience. I'm genuinely happy to have tried this new approach, and I believe it has significantly broadened my perspective on how we can build software more efficiently and intelligently. I hope this blog post has provided some valuable insights into the process!

The last paragraph was written by the Agent if you couldn’t tell ;)

To write this post I’ve distilled information from The Rust on ESP Book (licensed under CC-BY-SA v4.0), and I highly recommend giving it a read, especially if this topic interests you, as it trumps this blog post in detail and thoroughness.

Setup

Plug your ESP-32 in to a USB port on your machine. A light should turn on and you should now be able to see the serial port in your terminal.

ls /dev/ttyUSB0

your serial port name may be different here, this just happens to be mine.

Configure Your Host System

add yourself to the tty and dialout group. You’ll need this to be able to interact with the board over its serial connection.

sudo usermod -aG dialout <youruser>
sudo usermod -aG tty <youruser>

After this, logout and log back in to your machine, check that you are a member of these groups with groups

On your host system install cargo generate. We’ll be using this to generate a template, meaning all the extra code and configuration we need for the ESP-32.

cargo install cargo-generate

Note: on my system, I had to install openssl-dev on my host to compile past errors.

Generate Your Code

Now generate the required template for our system.

cargo generate esp-rs/esp-idf-template cargo

you'll see a TUI menu, set the project name to hello_world, the MCU to esp32, and don’t configure advanced options.

You can read this section of the tutorial I mentioned above if you want to know more about the generator.

You should now see some new files! The most important of which is src/main.rs.

Create Build Environment

Now we need to create the build environment. We’ll be using the container provided by espressif, since it already has all the configurations and packages requires.

Change directories into your generated project, pull the container, and start it:

cd hello_world
docker pull espressif/idf-rust:all_1.83.0.1
docker run -it -v $PWD:/home/esp/hello_world  espressif/idf-rust:all_1.83.0.1 bash

the above docker command will start an interactive shell inside the container, and mount a volume of your generated project inside of it.

You should have now have a shell inside the container:

Build, Flash and Run, Code

In the container shell, cd into the hello_world directory and build the code as you would any other Rust project:

cd hello_world
cargo build

After some time, your build will finish.

Back on the hosts shell, install espflash. This is a neat little tool that makes flashing the ESP32 as easy as 01,10,11 :)

cargo install espflash

For install errors, I had to install systemd-devel for the this to work.

Now that we're installed, let's flash our code to the board!

espflash flash target/xtensa-esp32-espidf/debug/hello_world --monitor

This command will both flash to the board, as well as monitor on the serial port for any logging.

The ESP-32 will automatically run your code on boot, so you wont need to do anything else here.

Success! Now you can play around on your own here. I personally just like to set up an infinite loop for fun :)

Next Steps

Now that you have a system set up to run Rust code on the ESP-32, the world is your oyster! I urge you to find more examples to broaden your horizon, or just experiment a little! Take a look at the esp-rs website for some other reccomendations, and good luck! 🫡

Footnote

This post could not have been written without help from The Rust on ESP Book. I’ve distilled information from that book, as well as included some of my own. That book is licensed under CC-BY-SA v4.0.

This is part of my independent study course on Embedded Linux and follows from many of my past blogs.

My final unit is an intro to Drivers for Linux systems. This blog post will only be on the practical methods of how to write and use a basic driver for a Linux system. Much of the theoretical knowledge from this can be found by reading the free book Linux Device Drivers, Third Edition.

Hello World!

I assume that you, the reader, have taken at least one programming course (It would be quite silly if you were looking to program and insert a Linux Kernel Module if you hadn't). So as you know, 'Hello world!' is the first exercise many of us follow when trying something new. So, we're going to keep that tradition alive with our first Kernel Module.

Our code for this exercise will be basic familiar C, with some new macros and header files you may not have used before:

#include <linux/module.h>    /* Needed by all modules */
#include <linux/kernel.h>    /* Needed for KERN_INFO */

int init_module(void){
    printk(KERN_INFO "Hello World!\n");

    return 0;
}

void cleanup_module(void){
    printk(KERN_INFO "Goodbye World.\n");
}

MODULE_LICENSE("GPL");

As you see, main() has been replaced by init_module(). They essentially act as the same thing, init_module() is the entry point for the file once it has been inserted into the kernel.

printk looks strikingly similar to printf with the addition of the KERNEL_INFO macro. This macro can be one of many things. One could find all of the options here, and more about printk on this kernel.org page.

Copy this code, and name the file hello.c

Compiling This Code

If you've been following my other blog posts, you might know that there is some setup that needs to be done to compile this code for our ARM board. The additional trouble comes here when we need special Linux header files to link to our code (linux/module.h and linux/kernel.h).

The Makefile

A Makefile will make this considerably easier, as there are a few compile steps needed:

CC = $(CROSS_COMPILE)gcc

obj-m := hello.o
KDIR := ~/buildroot/output/build/linux-6.0.9

all:
    $(MAKE) -C $(KDIR) M=$(PWD)

Create a file named Makefile in the same directory as your code file, and copy this into it.

You will need to change the KDIR variable to be specific to your setup. This variable should be the path to the Linux source files that buildroot compiles for your board. These can be found at buildroot/output/build/linux-YOURVERSION. This points our compiler to the object files we need to link against.

If you were writing modules for your desktop computer, KDIR should point at the kernel headers specific to the version your PC is running on. But this is just an interesting tidbit, and we are writing for only our board today.

The Cross-compiler

We want to use the same compiler that buildroot uses to compile all the programs and Linux kernel. It might be possible to use another ARM compiler, but when it comes to compiling for different boards, and all of the minute configurations that can be done to these compilers, let's play it safe and use the same one.

If you're following my configuration from my earlier blog, you can find your compiler in buildroot/output/host/bin/. The one we need is the arm-none-linux-gnueabihf-gcc.

We need to tell our Makefile to use this compiler, otherwise, it will default to the gcc we have installed on our Linux desktop.

To compile our code, run the following command in the directory which contains the code file, and Makefile (of course changing the path to be valid on your machine):

make CROSS_COMPILE=~/buildroot/output/host/bin/arm-none-linux-gnueabihf- ARCH=arm

We didn't include the gcc on the end, because that is implied with the Makefile

Running this, your code should compile, and you should see a bunch of new object files, but the most important one for us is the hello.ko file. This is a compiled kernel object file which we can use on our buildroot Beagelbone board.

Inserting The Kernel Module

Copy this file onto the board. If you have the correct configuration, you can scp or sftp this file. Otherwise, you can copy this to the SD card.

In the terminal on the board, insert the module with insmod hello.ko. Check the kernel output with cat /var/log/messages. You should see your Hello World!

To remove this module, simply rmmod hello.ko. Check the output again and you'll see Goodbye world.

Congratulations! You just wrote your first kernel code.

Intro to GDB and Valgrind

GDB

GDB is a full-featured and open-source debugger. It is integrated into VSCode and given a very pretty front end.

It is possible to remote debug with VSCode and GDB, but often many embedded development environments run it in its natural form on the terminal.

Valgrind

Valgrind opposed to GDB is a runtime tool. It analyses the stack, heap and disassembly of the program to primarily find and report memory leaks.

It can be used for much more, including cache usage and miss reports, deadlocks and race conditions, and heap memory usage.

GDB

Packages

I had to enable some settings in the buildroot menu for GDB to be present and working on the board:

• BR2_PACKAGE_HOST_GDB, in Toolchain | Build cross gdb for the host

• BR2_PACKAGE_GDB, in Target packages | Debugging, profiling and benchmark | gdb

• BR2_PACKAGE_GDB_SERVER, in Target packages | Debugging, profiling and benchmark | gdbserver

• BR2_ENABLE_DEBUG, in Build options | build packages with debugging symbols

  • This one specifically builds the included C libraries with debugging symbols.

Running the Code

In order to connect to the board, and run gdb remotely, we need to run this command on the board:

gdbserver --multi :2000 ./linked_list

Which outputs:

Process ./linked_list created; pid = 168
Listening on port 2000

and then start gdb on our pc

gdb

Which when running, looks like:

To connect to the board we need to run:

target extended-remote 192.168.1.100:2000

Where the IP address is that of the board, and the port 2000, is what we told GDB to use.

Compiling and Placing On board

We should compile this program using the cross-compiler provided by buildroot. It is found in output/host/bin/arm-none-linux-gnueabihf-gcc and we can add this to our PATH to make it easier and faster to compile our programs.

We need to do this because buildroot doesn't include a compiler when it builds the images. It is intended for final products mostly.

We can compile on our machine and sftp it over with:

sftp root@192.168.1.100

Debugging

The most basic commands for GDB are:

1. run - starts the execution of the program being debugged.

2. break - sets a breakpoint at a specified location in the program.

3. step - executes the current line and stops at the next line in the source code.

4. next - executes the current line and stops at the next line, but does not enter function calls.

5. continue - resumes execution until the next breakpoint or until the program terminates.

6. print - prints the value of a specified variable or expression.

7. backtrace or bt - prints the stack trace of the program at the current point of execution.

8. list - displays the source code around the current point of execution.

9. info - displays various types of information about the program being debugged, such as registers, breakpoints, and threads.

10. quit - exits GDB.

we can use this to trace along our program like in vscode

I'll set a breakpoint at the 'main' function with b main

and run the program, stepping with next

You can see that this follows along the code file that we have:

GDB also has a nice Text-User-Interface, or TUI that you can enter with Ctrl-X-A

Let's try out a few of these commands:

We can set breakpoints with 'b' and see them with the info command:

And delete them with 'delete'

There are many more commands, and gdb is one of those tools that can take time to master. This was just a simple lab, however.

Valgrind

I ran valgrind on a program I wrote in High-Performance Computing. This was a hastily poorly written program with little care for memory cleanup so I knew it would be leaky.

There isn't much to it. You can see output from valgrind with a summary of any memory leaks by running:

valgrind --leak-check=full ./program

Below is what is outputted (concatenated because it's super long):

==7144== Memcheck, a memory error detector

==7144== Copyright (C) 2002-2022, and GNU GPL'd, by Julian Seward et al.

==7144== Using Valgrind-3.20.0 and LibVEX; rerun with -h for copyright info

==7144== Command: mpirun -np 4 ./halo

==7144==

...

==7144==

==7144== LEAK SUMMARY:

==7144== definitely lost: 6,705 bytes in 24 blocks

==7144== indirectly lost: 31,491 bytes in 465 blocks

==7144== possibly lost: 0 bytes in 0 blocks

==7144== still reachable: 829 bytes in 21 blocks

==7144== suppressed: 0 bytes in 0 blocks

==7144== Reachable blocks (those to which a pointer was found) are not shown.

==7144== To see them, rerun with: --leak-check=full --show-leak-kinds=all

==7144==

==7144== For lists of detected and suppressed errors, rerun with: -s

==7144== ERROR SUMMARY: 21 errors from 21 contexts (suppressed: 0 from 0)

As you can see, there are quite a few leaks in this program. It's run with MPI, and I didn't take into great consideration the cleaning up of the memory.

Today we're going to set up networking and an HTTP server on the board to serve web pages.

Why might we want to do that?

Take for example any IoT device like this Smart Washing Machine, rather than running a cycle by having the user SSH into the Linux board and run scripts, one might run an HTTP server on the board and show a pretty website with nice features that anyone could use.

Modify the Buildroot Image

We need to add some extra packages to our board, mainly the HTTP Server.

Just like last time, change into your buildroot directory, and run:

make menuconfig

You should see the familiar menuconfig page:

• In Target Packages: Networking applications:

  • Enable nginx, make sure http_server is enabled

  • Enable dropbear. This is an SSH client that will be convenient for us.

  • Enable ifupdown scripts. These are init scripts courteously written for us to initialize our static network connection on the board.

Set up Networking

To connect our board to a network, we need a connection to our desktop.

Normally, you could do this by plugging your board into your router and letting it assign an IP address, but my router is pretty far from my desk so we'll have to use another method.

Option 1

If you have a network switch laying around, like this little Netgear one I have, you could use that:

Option 2

You could use a Crossover Cable. This will allow you to connect your desktop directly to the Beaglebone.

Setting IP Addresses

Like I spoke about before, your router could just assign the board an IP address. This is because the router is running a DCHP Server that assigns IP's for every computer on your network.

Since we are connecting our PC directly to our board, this will be a separate network from your router and will require different configuration.

We could run a DCHP server on our Desktop to assign the board an IP, but because we're only connecting one thing to this network, that is certainly overkill.

We'll define a static address for our board in its /etc/network/interfaces file.

Making an Overlay Directory

Instead of SSH'ing into the board every time we create a new image to modify this file, we can use an overlay file. This is an option in the buildroot menuconfig to allow us to add things into the image each time it builds.

In the buildroot directory, create and overlay directory, and fill it with the directories and files we need:

mkdir -p overlay/etc/network
touch overlay/etc/network/interfaces
vi overlay/etc/network/interfaces

In this vi window, paste:

auto eth0
iface eth0 inet static
    address 192.168.1.100
    gateway 192.168.1.1
    netmask 255.255.255.0

Here what we are doing, is setting our ethernet interface, eth0, to have a static ip address of 192.168.1.100, and giving it the gateway of 192.168.1.1.

Now enter the menuconfig, and in System Configuration, set the Root filesystem overlay directory to ./overlay

Now run make to build this new image, flash it onto your SD card when you're finished.

Plug the board in and boot it holding the USR button as usual. Plug your crossover cable or switch into both the board and your desktop.

In Settings, if you're running the GNOME Desktop Environment, go into network. You won't see a connection to your board yet, because you havent configured the static IP for your desktop.

Add a Wired network, and set your settings as follows:

The last set of numbers on your address can be whatever you'd like (except the IP you used for the beaglebone), I just used 192.168.1.45.

Save this network, and you should now see that you're connected to a wired network!

SSH

Now we should be able to ssh into our board.

ssh root@192.168.1.100

You'll notice ssh is acting very sluggish upon connection. There is something we can disable on the image to fix this.

In the menuconfig, navigate to the dropbear package. Inside this, disable reverse DNS Lookups.

Reverse DNS Lookup is a security feature, normally used to verify the authenticity of connections. But since our beaglebone isn't connected to any DNS server it will hang here as it screams out into nothing, waiting for a return from a non-existent DNS server.

Build this image and put it onto your card, and SSH access should be fast now!

Serving Web Pages

Busybox init handles a lot of the work for us here. Because we enabled nginx, buildroot has assumed that we want it to run each time on startup.

With the board booted up, and network cable connected, you should be able to go directly to 192.168.1.100 in your browser and get the nginx configure page:

According to

Next, we need to provide some basic configuration to NGINX to serve our custom pages. In the The NGINX Beginners Guide, we learn that the configuration file for nginx is in /etc/nginx/nginx.conf and has a relatively simple configuration process.

Instead of doing this on our board, where every time we reinstall an image we'd have to repeat this process, lets automate this through the use of the overlay directory.

Back in your buildroot diretory, cd into your overlay directory.

mkdir -p etc/nginx/
touch etc/nginx/nginx.conf

In a text editor, enter the following simple config into nginx.conf :

worker_processes  1;

events {
    worker_connections  1024;
}


http {
    include       mime.types;
    default_type  application/octet-stream;

    sendfile        on;
    keepalive_timeout  65;

    server {
        listen       80;
        server_name  localhost;

        location / {
            root  /data/www;
            index  index.html;
        }
    }
}

This tells nginx we want to serve out of /data/www which is the recommended location in the aforementioned beginner's guide.

Create this directory in the overlay as well:

mkdir -p data/www
touch data/www/index.html

In a text editor, let's add a "Hello world page" to demonstrate a working embedded web server:

<!DOCTYPE HTML>
<html>
<body>
  <script>
    alert( 'Hello world from the BeagleBone Black!' );
    document.write('Hello world from the BeagleBone Black!');
  </script>
</body>
</html>

After this, run make to build the image, flash it to the board, and boot it familiarly.

Navigate to the board's address in the browser, and:

Success! We can serve web pages from the beaglebone to your desktop!

I'm going to be using Buildroot in this tutorial. I chose Buildroot as it is one of the less complex and more widely used build systems in the embedded Linux space. Yocto is arguably better for a production scenario but takes much longer to master due to its complexity. Buildroot is simple but lacks many of the bells and whistles that Yocto has.

Much of this blog is based on bootlin's training documentation, so it may be more useful for you to follow along with that as well as this blog.

What is a Build System?

A build system is a lot of things and can look very different depending on the project. A build system in its easiest description is translating source code into binary files to be run on a system.

A simple build system could be a single makefile that compiles a single C program. Example below:

#include <stdio.h>

int main(){
    printf("Hello World!\n");

CC=gcc

hello:
        $(CC) hello.c -o hello

This is likely one of the simplest forms of build systems possible. It might almost be stretching it calling it a 'system' because of how minimal it is.

Buildroot is similar to this (but much much more complex). It does what this simple makefile does, except it compiles the Linux kernel, bootloader, any modifications you have, and many more, all according to the configurations you input.

Embedded Linux build systems automate so much that building from scratch is essentially obsolete except in some very interesting edge cases.

Getting Buildroot

First, as always, clone the git repository:

git clone https://git.buildroot.net/buildroot

Switch into the cloned repo, and checkout the newest build

cd buildroot 
git checkout 2022.11

Configuring Buildroot

Buildroot uses the same menuconfig we saw in earlier blog's that crosstool and the Linux kernel does, so enter that with:

make menuconfig

I'm closely following Buildroot's Training Document here With the largest change being that my BeagleBone is the non-wireless version, and thus uses a different device tree.

Do experiment with these options on your own time, or take some time to see what other options are available in the menuconfig. There are quite a few interesting options that are easy to implement.

• In Target Options:

  • Select ARM (little endian) as the Target Architecture

  • Select cortex-A8 as the Target Architecture Variant

• In Toolchain:

  • Set toolchain type to External toolchain . (This will save us a lot on build time).

  • Set the Toolchain under Toolchain External Options as ARM 2021.07 .

• In System Configuration:

  • Set the System hostname to something of your preference. I used billbeaglebone .

  • Set the System banner as well to anything of interest. This is a line of text that will print every time you turn the system on. Mine is Bill's Embedded Linux!

  • Enable root login with password and set this password.

• In Kernel:

  • Enable Linux Kernel, the default should be the newest kernel (at the time of reading 6.0), this is fine for our use.

  • Define the Defconfig name as omap2plus.

  • Make sure the Kernel binary format is zImage .

  • Define the In-tree Device Tree Source File name as am335x-boneblack .

  • Enable Needs host OpenSSL

• In Target Packages:

  • Enable BusyBox.

  • Optional: For a later blog, we will be debugging a program on the board using GDB and Valgrind. In Debugging, profiling and benchmark enable GDB and gdbserver, as well as valgrind .

  • Optional: in Networking applications enable dropbear. This is an SSH client that will be convenient to use later.

  • Optional: For a little fun, in Games enable ascii_invaders .

  • Take a look around here at all the packages you can include so simply with Buildroot. If you followed the last blog series on creating an embedded Linux system from scratch, you might appreciate just how easy this is.

• In Bootloaders:

  • Enable U-Boot.

  • Define the U-Boot configuration as am335x_evm .

  • Set the Build system Kconfig.

  • Check that the U-Boot Version is set 2022.04 .

  • In U-Boot binary format, enable only u-boot.img .

  • Enable Install U-Boot SPL binary image, and set U-boot SPL/TPL binary image name(s) to MLO .

This finishes our configuration! Go ahead and save before exiting.

Building Your System

For curiosity, Bootlin notes we should save the build log. If you don't care about this, you can just run make. But if you're interested like I am to see the build log, run make 2>&1 | tee build.log which will save the make and terminal logs to a build.log file.

The first time you build will take a while. Skip to 'Prepping the SD Card' in the interest of time.

Once the build is done, and you've dealt with any errors that may have come up (I had to install perl on my system), you should see these output files in the output/images directory.

Prepping the SD Card

You should use a good SD card for this. At first I tried the Kingston CANVAS Select Plus, but experienced issues with the read/write speeds. I upgraded to the SanDisk Extreme and had no issues.

We need to create two partitions on our card. You can use command line tools, or something easy like GParted.

Create two partitions, the first a FAT32 filesystem with 128Mib, and the second a ext filesystem taking up the remaining space on the card.

You should end up with partitions looking similar to this:

Label the partitions as I did for ease of use, and set the boot flag on the boot partition by left-clicking, and selecting Manage flags .

Prepping Our Linux System

Once the build finishes, and you have your SD Card formatted, we are ready to move our files over to the BeagleBone.

Follow the steps in my earlier blog to connect a serial adapter, and install picocom .

Copy the files from the output/images directory onto the boot partition like so:

#On Fedora Linux, the SD card is mounted at /run/media/$USER/partitionname, this may be different depending on your distro.
cp MLO u-boot.img zImage am335x-boneblack.dtb /run/media/$USER/boot/

We can create a file to give U-Boot commands without setting the bootloader manually. Create a folder and file in the boot partition:

mkdir extlinux && touch extlinux/extlinux.conf

Fill this file with the following text:

label buildroot
        kernel /zImage
        devicetree /am335x-boneblack.dtb
        append console=ttyO0,115200 root=/dev/mmcblk0p2 rootwait

If you follow this from my earlier blog, you might notice this is very similar to the commands we gave to U-Boot manually.

Finally, we need to unpack our root file system now to the second partition:

sudo tar -C /run/media/$USER/rootfs/ -xf rootfs.tar

Now our card is ready for the BeagleBone!

Booting Our System

With your serial adapter plugged into your PC, start up a picocom terminal:

picocom -b 115200 /dev/ttyUSB0

Now, unmount the SD card's partitions, and insert the card into the board.

While plugging in the board, hold down the USR button to force the system to boot from the SD card.

You should see U-Boot and kernel output similar to this:

Finally followed with the banner you set in the Buildroot menuconfig.

Login as root with the password you supplied:

And you've now installed a Buildroot Linux system on the board!

If you followed the optional steps in the config step, enjoy some ascii_invaders:

This finishes the tutorial. Thanks for reading!

This blog is based on Bootlin's Embedded Linux Course as well as Frank Vasquez and Chris Simmonds Mastering Embedded Linux Programming, so you may have some success reading their materials alongside this blog.

In this section, we will finish our setup of a barebones Linux system for the Beaglebone Black. The Root Filesystem is the last essential piece of the Linux system. Ours will contain a familiar directory structure, as well as many of the basic programs you might be used to from a desktop Linux distribution.

Creating a Root Filesystem From Scratch

The first step in this process is to create a staging directory in which to place the filesystem hierarchy for our future Beaglebones rootfs.

mkdir bin dev etc home lib proc sbin sys tmp usr var && mkdir usr/bin usr/lib usr/sbin var/log

Take a look at this structure with tree -d, which should now look like:

.
├── bin
├── dev
├── etc
├── home
├── lib
├── proc
├── sbin
├── sys
├── tmp
├── usr
│   ├── bin
│   ├── lib
│   └── sbin
└── var
    └── log

Programs Needed for the rootfs

According to Mastering Embedded Linux Programming - "Even for a basic root filesystem, you need approximately 50 utilities..." It goes on to mention that tracking down this source code for ourselves might be a true pain. (BusyBox)[https://busybox.net/] solves that problem for us. You can read more about BusyBox somewhere else, but all that is necessary to know here, is it provides us with the essential Linux utilities that we need, in a minimal package size.

Clone the git repo, and switch to a stable release with:

git clone git://busybox.net/busybox.git
cd busybox
git checkout 1_35_0

Build the default configuration of BusyBox

make distclean
make defconfig

Export the toolchain and architecture like we did in (Part 3)[https://blog.billvanleeuwen.ca/compiling-and-porting-the-linux-kernel-to-the-beaglebone-black] of this blog series to avoid typing it in each make command:

export ARCH=arm
export CROSS_COMPILE=arm-training-linux-uclibcgnueabihf-

We want to install BusyBox in our staging directory. Enter the menu config with

make menuconfig

Once in the menu, set the install path in Settings -> Destination path for 'make install'. This should be the path for your rootfs directory we just created.

We also want busybox to statically compile. This will reduce complexity for us.

Note on Static Compilation

You might not want to do this in most cases, as any further programs you install must also be statically compiled.

For the uninitiated Static Compilation is the process of compiling all of the needed libraries together with the program itself, rather than using them externally. This saves complexity, as you don't need to worry about including extra object files in your rootfs, but the compromise is size. Many of these programs rely on the same libraries. You can imagine it would save on space if we didn't have to include these in each compiled program, and instead have a single object file for these to all dynamically link against. For our purposes (essentially building a toy Linux system nobody is ever going to use in production) this is fine.

Now run make install to build Busybox.

On following the instructions from bootlin and Mastering Embedded Linux, this step returned me an error:

networking/ping.c:158:11: fatal error: netinet/icmp6.h: No such file or directory
  158 | # include <netinet/icmp6.h>

I likely made a mistake in configuring my toolchain.

We dont need ipv6 for our limited scope project, so if this happens to you, it can be solved by disabling ipv6 support in the BusyBox menu config under Networking Utilities -> Enable IPv6 Support

Try ```tree`` in your staging directory to see what buysbox installed

.
├── bin
│   ├── arch -> busybox
│   ├── ash -> busybox
│   ├── base32 -> busybox
│   ├── base64 -> busybox
│   ├── busybox
│   ├── cat -> busybox
│   ├── chattr -> busybox
│   ├── chgrp -> busybox
│   ├── chmod -> busybox
│   ├── chown -> busybox
│   ├── conspy -> busybox
│   ├── cp -> busybox

...

├── dev
├── etc
├── home
├── lib
├── linuxrc -> bin/busybox
├── proc
├── sbin
│   ├── acpid -> ../bin/busybox
│   ├── adjtimex -> ../bin/busybox
│   ├── arp -> ../bin/busybox
│   ├── blkid -> ../bin/busybox
│   ├── blockdev -> ../bin/busybox
│   ├── bootchartd -> ../bin/busybox
│   ├── depmod -> ../bin/busybox
│   ├── devmem -> ../bin/busybox
│   ├── fbsplash -> ../bin/busybox
│   ├── fdisk -> ../bin/busybox
│   ├── findfs -> ../bin/busybox

...

└── var
    └── log

16 directories, 397 files

Wow, look at all those programs! Imagine compiling and loading all of these yourself. Sheesh.

Testing our system

You should have two partitions on your SD card that we created in (part 2)[https://blog.billvanleeuwen.ca/porting-u-boot-onto-the-beaglebone] of this series.

Insert your SD card into the PC, and copy all of the files and folders from your staging directory to the rootfs partition on your SD card.

Eject the card, and slot it into your Beaglebone.

Like before, hold the USR button as you power up the Beaglebone, and spam the spacebar in the picocom terminal.

You should see the u-boot command line: =>

You should still have the bootcmd environment variable defined. We need to set another so that we can mount our rootfs and avoid the kernel panic from earlier.

setenv bootargs console=ttyO0,115200 root=/dev/mmcblk0p2 rootfstype=ext4 rootwait init=/bin/sh +m

This tells the system that we have our root filesystem on the second partition of our SD card.

Go ahead and reboot the system with boot.

You should now avoid the kernel panic, and see something like this in your console:

[    2.266649] VFS: Mounted root (ext4 filesystem) readonly on device 179:2.
[    2.274829] devtmpfs: mounted
[    2.279609] Freeing unused kernel image (initmem) memory: 1024K
[    2.288104] Run /sbin/init as init process
[    2.304033] mmc1: new high speed MMC card at address 0001
[    2.311922] mmcblk1: mmc1:0001 M62704 3.56 GiB 
[    2.319848]  mmcblk1: p1
[    2.323613] mmcblk1boot0: mmc1:0001 M62704 2.00 MiB 
[    2.335241] mmcblk1boot1: mmc1:0001 M62704 2.00 MiB 
[    2.350386] mmcblk1rpmb: mmc1:0001 M62704 512 KiB, chardev (250:0)
[    4.887550] random: crng init done
can't run '/etc/init.d/rcS': No such file or directory

Please press Enter to activate this console.

Great! Hit enter, and you now have a rather minimal Linux system running!

/ # ls
bin      etc      lib      proc     sys      usr
dev      home     linuxrc  sbin     tmp      var
/ # cd bin/
/bin # ls
arch           dumpkmap       kill           netstat        setserial
ash            echo           link           nice           sh
base32         ed             linux32        pidof          sleep
base64         egrep          linux64        ping           stat
busybox        false          ln             pipe_progress  stty
cat            fatattr        login          printenv       su
chattr         fdflush        ls             ps             sync
chgrp          fgrep          lsattr         pwd            tar
chmod          fsync          lzop           reformime      touch
chown          getopt         makemime       resume         true
conspy         grep           mkdir          rev            umount
cp             gunzip         mknod          rm             uname
cpio           gzip           mktemp         rmdir          usleep
cttyhack       hostname       more           rpm            vi
date           hush           mount          run-parts      watch
dd             ionice         mountpoint     scriptreplay   zcat
df             iostat         mpstat         sed
dmesg          ipcalc         mt             setarch
dnsdomainname  kbd_mode       mv             setpriv
/bin #

There is however an error from the kernel:

can't run '/etc/init.d/rcS': No such file or directory

/etc/init.d/rcS is supposed to be an init script called by busybox's init system. This needs to be defined by us, which we will do in the next step.

The Init system

Back in our staging directory, create two files.

cd etc
mkdir init.d
touch init.d/rcS
touch inittab

Copy the sample inittab file from (bootlins example)[https://elixir.bootlin.com/busybox/1.35.0/source/examples/inittab] into your inittab file

Because we aren't doing anything serious with our system. init.d/rCs can be left empty. Normally you could define any extra init scripts or commands in this file.

Copy these files over to your rootfs directory. Start up your Beaglebone by the method before and viola! The error should be gone!

Conclusion

You've now successfully ported a minimal Linux system onto the Beaglebone!

You could take this one step further and flash it onto the onboard eMMC, but for the sake of this blog series, I won't go into that here.

This blog is based on Bootlin's Embedded Linux Course as well as Frank Vasquez and Chris Simmonds Mastering Embedded Linux Programming, so you may have some success reading their materials alongside this blog.

In this section, we will be compiling, and configuring the Linux kernel and porting it to the Beaglebone Black.

If you haven't read Part 1 and Part 2 of this series, you may be lost.

Fetching the source code

First, clone the Linux repository into an appropriate directory.

git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux

This repository is, at the time of writing, 2.5GB, so go grab a coffee.

Now we have the Linux source code on our machine. However, these are the 'mainline' releases where we would be best off using the 'stable' releases. These are maintained in a separate repository. For more info on what this means, check out This Page on the differences.

cd linux
git remote add stable https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux
git fetch stable

This again may take a while depending on your internet speed.

Cross-compiling the kernel

At the time of writing, remotes/stable/linux-6.1.y is the latest stable release, you can check your branches with

git branch -a

You can check which kernel version the local repository is on with

make kernel version

My output was: 6.2.0-rc5

Aside - This means Linus Torvalds is currently working on releasing Linux 6.2.0, and on Release Candidate #5. Again, check This Page to learn more about what that means.

Let's choose the newest stable branch in an attempt to stay current.

git checkout remotes/stable/linux-6.1.y

Try make kernelversion again to see the difference.

Define some environment variables so Linux's make scripts know what we want to compile for an ARM board, and know what C compiler we want to use (make sure the cross-compiling toolchain we made in Part 1 of this blog series is on the PATH).

export ARCH=arm
export CROSS_COMPILE=arm-training-linux-uclibcgnueabihf-

Run make help. Without exporting the variables above, or including them in the command, your output will look much different. This will show you all of the configurations Linux can build for. Ours for the Beaglebone is multi_v7_defconfig (Frank Vasquez and Chris Simmonds Mastering Embedded Linux Programming says to use this one, while Bootlin says to use omap2plus_defconfig, but both worked for me.)

Enter the configuration menu with make menuconfig

In this menu, find and disable CONFIG_GCC_PLUGINS. Bootlin suggests this, as it will skip building special plugins which require extra dependencies, and we don't need them. You can find the location of this using typical vim commands. Enter / to search for this option.

Now, we're ready to compile the kernel!

# replace <n> with the amount of cores your CPU has to parallelize the build
make zImage -j<n>

Now sit back and wait for a bit. This will take a while depending on your CPU speed and core count.

Once the kernel compiles, you'll need to find two files and copy them to the boot partition of the SD card.

arch/arm/boot/zImage
arch/arm/boot/dts/am335x-boneblack.dtb

These are the kernel image, and the device tree file respectively.

Congratulations! You've compiled the kernel from source!

Booting the Kernel

Plug in your USB to TTL cable, and start-up picocom to get a serial connection to the Beaglebone.

picocom -b 115200 /dev/ttyUSB0

We still want to boot from the SD card, rather than the bootloader on the eMMC. Be ready to press the space bar on your keyboard to avoid going through U-Boot's auto-boot sequence. Hold down the USR button, and plug in the cord to provide power to the Beaglebone.

Be sure you're greeted by your bootloader rather than the one on the eMMC. Check the date, like from Part 2 of this series, and make sure it's the date in which you compiled U-Boot.

You should see the familiar prompt => on your picocom terminal.

Once the kernel boots up, we want it to send its output to its UART pins, which are the ones our USB to TTL converter are connected. Enter the following into your picocom terminal.

=> setenv bootargs console=ttyS0,115200n8
=> saveenv

Now we're going to load the kernel image, and device tree file into memory:

=> fatload mmc 0:1 0x80200000 zImage
=> fatload mmc 0:1 0x80f00000 am335x-boneblack.dtb

Let's boot this sucker!

=> bootz 0x80200000 - 0x80f00000

What you'll see in the output might look similar to:

[    0.000000] Booting Linux on physical CPU 0x0
[    0.000000] Linux version 6.1.7 (billsDesktop@fedora) (arm-linux-gcc (crosstool-NG 1.25.0.95_7622b49) 11.3.0, GNU ld (crosstool-NG 1.25.0.95_7622b49) 2.39) #2 SMP Mon Jan 23 20:25:30 EST 2023
[    0.000000] CPU: ARMv7 Processor [413fc082] revision 2 (ARMv7), cr=10c5387d
[    0.000000] CPU: PIPT / VIPT nonaliasing data cache, VIPT aliasing instruction cache
[    0.000000] OF: fdt: Machine model: TI AM335x BeagleBone Black

...

[    3.472852] Kernel panic - not syncing: VFS: Unable to mount root fs on unknown-block(0,0)
[    3.481165] CPU: 0 PID: 1 Comm: swapper/0 Not tainted 6.1.7 #2
[    3.487037] Hardware name: Generic AM33XX (Flattened Device Tree)
[    3.493177]  unwind_backtrace from show_stack+0x10/0x14
[    3.498478]  show_stack from dump_stack_lvl+0x40/0x4c
[    3.503584]  dump_stack_lvl from panic+0x108/0x33c
[    3.508434]  panic from mount_block_root+0x168/0x208
[    3.513462]  mount_block_root from prepare_namespace+0x150/0x18c
[    3.519523]  prepare_namespace from kernel_init+0x18/0x12c
[    3.525061]  kernel_init from ret_from_fork+0x14/0x2c
[    3.530156] Exception stack(0xe0009fb0 to 0xe0009ff8)
[    3.535240] 9fa0:                                     00000000 00000000 00000000 00000000
[    3.543464] 9fc0: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
[    3.551684] 9fe0: 00000000 00000000 00000000 00000000 00000013 00000000
[    3.558350] ---[ end Kernel panic - not syncing: VFS: Unable to mount root fs on unknown-block(0,0) ]---

This last section might be problematic for someone not in our shoes, but for us, this Kernel Panic is mentioning that we don't have a root file system mounted. That's OK, we'll get to that in the next blog series.

For now, let's be happy we've booted a cross-compiled Linux kernel on the Beaglebone!

Automate this process with a simple bootscript:

=> setenv bootcmd 'fatload mmc 0:1 0x80200000 zImage; fatload mmc 0:1 0x80f00000 am335x-boneblack.dtb; bootz 0x80200000 - 0x80f00000'
=> saveenv

This blog is based on Bootlin's Embedded Linux Course as well as Frank Vasquez and Chris Simmonds Mastering Embedded Linux Programming, so you may have some success reading their materials alongside this blog.

We now have to install the bootloader U-Boot (Das U-Boot is the full name) onto the board.

If you are not familiar, the bootloader is a piece of software that often runs first, or close to first on the hardware (dependent on the board architecture and some other things).

From Frank Vasquez and Chris Simmonds Mastering Embedded Linux Programming:

In an embedded Linux system, the bootloader has two main jobs: to initialize the system
to a basic level and to load the kernel. In fact, the first job is somewhat subsidiary to the
second, in that it is only necessary to get as much of the system working as is needed to
load the kernel.

Connect your serial adapter to the board

We need access to the Beaglebone, and the only way to do this once we load the bootloader is through the serial port.

Your serial adapter's colours may vary. So you may need to look up the spec for your cable. I'm using this Dtech USB to TTL cable I bought for $15 CAD on Amazon. You can likely find one cheaper direct from China if you're willing to wait for shipping.

2025, Sept - Edit: I’m looking back through these blogs to replicate this previous work. I’ve realised the photo here is incorrect. The TXD and RXD are swapped.

The pins are labelled 1-6 from right to left (in the perspective of this image). Pin 1 is ground, 4 and 5 are the boards Rx, and Tx respectively Pin 4 is the TXD and 5 is the RXD. Tx is SEND and Rx is RECIEVE, so you need to reverse this order for your cable such that the cables Tx is plugged into the boards Rx, and vice versa.

To communicate with the board, you will need a serial communication program. picocom is a good and minimal choice for our use. In order to get access to the serial port, you need to add yourself to the dialout group.

sudo dnf install picocom
sudo usermod -a -G dialout $USER

You will need to reboot for the dialout change to take affect. You CAN access /dev/ttyUSB0/ as root, or with sudo but you SHOULD NOT run things as root unless you have to, with the risk of ruining your system.

Cross-compiling U-Boot

You should have your cross-compiler set up from Part 1 of this series. If not, you wont be able to continue from here on out.

Check out the U-Boot source code from gitlab (the github version is an identical mirror, and will work just fine if that's your preference).

Bootlin releases the source code as commits in its git repository. Clone the source and check out the latest release with:

git clone https://source.denx.de/u-boot/u-boot.git
cd u-boot
git checkout v2023.01

To understand the compilation steps further than this tutorial for u-boot, see the README.

Since we are cross-compiling:

If you are not using a native environment, it is assumed that you have GNU cross compiling tools available in your path. In this case, you must set the environment variable CROSS_COMPILE in your shell. Note that no changes to the Makefile or any other source files are necessary. For example using the ELDK on a 4xx CPU, please enter:

    $ CROSS_COMPILE=ppc_4xx-
    $ export CROSS_COMPILE

We can shorten this to a simple one-liner with:

export CROSS_COMPILE=arm-linux-

U-Boot is intended to be simple to build. After installing the sources you must configure U-Boot for one specific board type. This is done by typing:

make NAME_defconfig

where "NAME_defconfig" is the name of one of the existing configu- rations; see configs/*_defconfig for supported names

To configure U-Boot for our board:

make am335x_evm_defconfig .

Now, depending whether you have the wired or wireless beaglebone, run:

make DEVICE_TREE=am335x-boneblack

or

make DEVICE_TREE=am335x-boneblack-wireless

You are now building U-Boot!

From bootlin:

The DEVICE_TREE variable specifies the specific Device Tree that describes our hardware board.

Prepping the SD Card

From bootlin:

The TI romcode will look for an MLO (MMC Load) file in a FAT partition on an SD card. This is precisely what U-Boot compiled for us, together with the U-Boot binary (u-boot.img).

Insert the SD card into your PC. I don't have a port for one, so I'm using a USB adapter. Find the SD card 'device filename':

dmesg

your output will look something like:

[10600.641343] usb 2-3: new SuperSpeed USB device number 4 using xhci_hcd
[10600.661566] usb 2-3: New USB device found, idVendor=8564, idProduct=4000, bcdDevice= 0.38
[10600.661574] usb 2-3: New USB device strings: Mfr=3, Product=4, SerialNumber=5
[10600.661578] usb 2-3: Product: Transcend
[10600.661581] usb 2-3: Manufacturer: TS-RDF5 
[10600.661584] usb 2-3: SerialNumber: 000000000037
[10600.668454] usb-storage 2-3:1.0: USB Mass Storage device detected
[10600.669577] scsi host9: usb-storage 2-3:1.0
[10601.697428] scsi 9:0:0:0: Direct-Access     TS-RDF5  SD  Transcend    TS38 PQ: 0 ANSI: 6
[10601.697881] sd 9:0:0:0: Attached scsi generic sg0 type 0
[10602.090927] sd 9:0:0:0: [sda] 124735488 512-byte logical blocks: (63.9 GB/59.5 GiB)
[10602.092385] sd 9:0:0:0: [sda] Write Protect is off
[10602.092391] sd 9:0:0:0: [sda] Mode Sense: 23 00 00 00
[10602.093987] sd 9:0:0:0: [sda] Write cache: disabled, read cache: enabled, doesn't support DPO or FUA
[10602.102665]  sda: sda1
[10602.102917] sd 9:0:0:0: [sda] Attached SCSI removable disk

What we can gain from this output, is that we have a SCSI disk attached. (If you're unfamiliar, SCSI is both an older physical interface, and a communication standard for disks. Though we have attached an SD card, Linux will always see it as a SCSI disk).

This line [10602.102665] sda: sda1 shows that this disk is named sda1, or 'SCSI Disk A 1'. This lives in /dev/sda1.

We need to unmount any partitions of this SD card before modifying its partition table. Check if any are mounted with:

sudo mount | grep sda1

which might output:

/dev/sda1 on /run/media/billsDesktop/16E3-7820 type exfat (rw,nosuid,nodev,relatime,uid=1000,gid=1000,fmask=0022,dmask=0022,iocharset=utf8,errors=remount-ro,uhelper=udisks2)

If this, or any others are mounted, unmount them with

sudo umount /dev/sda1*

Manually erase the partition table on this card with:

sudo dd if=/dev/zero of=/dev/sda1 bs=1M count=16

Note: My post deviates from bootlin's material here. I found their method didn't work for me. This method is from Frank Vasquez and Chris Simmonds Mastering Embedded Linux Programming. The authours have a script to do this as well on the book's github page

Create two partitions on the card with:

sudo sfdisk /dev/${DRIVE} << EOF
,64M,0x0c,*
,1024M,L,
EOF

What we did here was manually add a partition table to the card. One 64MB, FAT32, bootable partition, and another 1GB ext4.

We only need the one for now, but once we mount a root filesystem in a later blog, it will be useful that we've already done it.

Create FAT16 and ext4 filesystems on this partition with:

sudo mkfs.vfat -a -F 16 -n boot /dev/sda1p1
sudo mkfs.ext4 -L rootfs /dev/sda1p2

This should mount to your PC automatically. If not, remove and reinsert the SD card.

What we've done above might also be possible using a GUI tool like GParted

Now we that have a bootable partition on the card, go ahead and copy the compiled U-Boot image onto the card.

The directory for the SD card may be dependent on your workstations distribution, and whether you are using a USB adapter or inserting it directly into the PC. You should also just be able to drag and drop the files in the file explorer.

cp MLO u-boot.img /run/media/$USER/boot/

Testing U-Boot

Make sure your USB to Serial connector is plugged into the board and your PC from earlier.

Start monitoring the serial port with:

picocom -b 115200 /dev/ttyUSB0
#-b is setting the baud rate for the asynchronous serial connection

Insert the SD card into the beaglebone with no power going to it. Hold down the small black button next to the SD card, plug in the power cable, and let go of the button after a few seconds.

Your output should start with something like this:

U-Boot SPL 2023.01 (Jan 21 2023 - 23:09:14 -0500)
Trying to boot from MMC1


U-Boot 2023.01 (Jan 21 2023 - 23:09:14 -0500)

CPU  : AM335X-GP rev 2.1
Model: TI AM335x BeagleBone Black
DRAM:  512 MiB
Core:  160 devices, 18 uclasses, devicetree: separate
WDT:   Started wdt@44e35000 with servicing every 1000ms (60s timeout)
NAND:  0 MiB
MMC:   OMAP SD/MMC: 0, OMAP SD/MMC: 1
Loading Environment from FAT... Unable to read "uboot.env" from mmc0:1... 
<ethaddr> not set. Validating first E-fuse MAC
Net:   eth2: ethernet@4a100000, eth3: usb_ether
Hit any key to stop autoboot:  0 
switch to partitions #0, OK
mmc0 is current device
Scanning mmc 0:1...
No EFI system partition
BootOrder not defined
EFI boot manager: Cannot load any image
switch to partitions #0, OK
mmc1(part 0) is current device
Scanning mmc 1:1...
BootOrder not defined
EFI boot manager: Cannot load any image
## Error: "bootcmd_nand0" not defined

...

Make sure the date and time are correct for when you compiled U-Boot. Otherwise, the beaglebone is booting the preloaded U-Boot from its internal eMMC. If it's off, you've done something wrong.

The output will be followed by:

=>

Which is the U-Boot command line! SUCCESS! You are officially running your own cross-compiled bootloader.

Playing With U-Boot

We have completed this blog section, but in case you were more curious about U-Boot, enter help to see the commands available to U-Boot :)

This blog is based on Bootlin's Embedded Linux Course as well as Frank Vasquez and Chris Simmonds Mastering Embedded Linux Programming, so you may have some success reading their materials alongside this blog.

The Toolchain Generator

Crosstool-ng is a cross-compiling toolchain generator.

For those that don't know, a cross-compiling toolchain is not much different from a general toolchain you might use in regular C/C++ development (for example gcc or g++). However, the cross-compiler generates binaries for other architectures, in this case, ARM.

Our toolchain needs to have some special setup though. To write code to interface with the kernel, we need the Linux kernel headers. Therefore, our toolchain needs to insert these headers, as well as a specific C library.

We're going to use uClibc for our project. uClibc is a very small C library designed for embedded applications. It has a focus on small size over performance.

Compiling crosstool-NG

I am semi-following the instructions from the crosstool-NG documentation

First, clone the git repository.

git clone https://github.com/crosstool-ng/crosstool-ng
cd crosstool-ng/

Next, we need to configure and build the source code. There are two ways to do this, however, I'll be following the hacker's way which allows us to run this locally, rather than exporting it to the PATH.

./bootstrap
./configure --enable-local

Likely you will need to run this configure script multiple times, installing missing packages along the way. If you're not on Ubuntu like me, you might need to do some tactical googling along the way to discover the alternate package names.

after fiddling, you can compile.

make

Creating the toolchain

you can see the help menu by entering:

./ct-ng help

we want to use the cortex a8 sample since that will remove much of the configuring we might need to do. you can see all the samples with:

./ct-ng list-samples

we like the a8 one, so:

./ct-ng arm-cortex_a8-linux-gnueabi

ok, now let's enter the menu and configure our toolchain

./ct-ng menuconfig

the menu should look something like this:

Configure the toolchain as follows (excerpt from embedded-linux-bbb-labs.pdf):

In Path and misc options:

• Change Maximum log level to see to DEBUG (look for LOG_DEBUG in the interface, using the / key) so that we can have more details on what happened during the build in case something went wrong.

In Target options:

• Set Use specific FPU (ARCH_FPU) to vfpv3.

• Set Floating point to hardware (FPU).

In Toolchain options:

• Set Tuple's vendor string (TARGET_VENDOR) to training.

• Set Tuple's alias (TARGET_ALIAS) to arm-linux. This way, we will be able to use the compiler as arm-linux-gcc instead of arm-training-linux-uclibcgnueabihf-gcc, which is much longer to type.

In Operating System:

• Set Version of linux to the 5.15.x version that is proposed. We choose this version because this matches the version of the kernel we will run on the board. At least, the version of the kernel headers are not more recent.

In C-library:

• If not set yet, set C library to uClibc-ng (LIBC_UCLIBC_NG)

• Keep the default version that is proposed

• If needed, enable Add support for IPv6 (LIBC_UCLIBC_IPV6)2 , Add support for WCHAR (LIBC_UCLIBC_WCHAR) and Support stack smashing protection (SSP) (LIBC_UCLIBC_HAS_ SSP)

In C compiler:

• Set Version of gcc to 11.3.0. We need to stick to gcc 11.x, as Buildroot 2022.02 which we are going to use later doesn’t support gcc 12.x toolchains yet: gcc 12.x was released after Buildroot 2022.02.

• Make sure that C++ (CC_LANG_CXX) is enabled

In Debug facilities:

• Disable duma, gdb, ltrace. They will not be needed for the labs that will use this toolchain.

• Keep only strace (DEBUG_STRACE) enabled

now, we are ready to build the toolchain:

./ct-ng build

this may take a while, as we're building an entire arm compiler, linker, debugger, etc.

Now that it's built, you should add $HOME/x-tools/arm-training-linux-uclibcgnueabihf/bin to your PATH. My perfered way of doing this is modifying your ~/.profile file which should define your PATH.

Confirm that the toolchain works.

take this ultra-simple C file:

#include <stdlib.h>
#include <stdio.h>

int main (void)
{
    printf( "Hello world!\n" );
    return EXIT_SUCCESS;
}

Create a hello.c file, and put this as the contents.

try compiling with arm-linux-gcc -o hello hello.c

if you receive bash: arm-linux-gcc: command not found... you haven't added the compiler to your PATH properly.

otherwise, you should now see your compiled C file. Typically, you would run this file with ./hello, but you will receive bash: ./hello: cannot execute binary file: Exec format error. This is because we've now compiled this binary to ARM rather than X86, which is what we wanted!! :)

In order to test this, we'll need an arm VM. qemu is the obvious choice here. Go ahead and install it with sudo dnf install qemu-user if you are a fellow RHEL/Fedora user like yours truly. sudo apt install qemu-user will work if you use Ubuntu or a Debian-based distro.

Try running the binary with qemu-arm hello.

You will receive the error /lib/ld-uClibc.so.0: No such file or directory. This is because qemu is missing our C library, uClibc. This was compiled into an object file by our configuration with crosstool-NG. Tell qemu where to find it with qemu-arm -L ~/x-tools/arm-training-linux-uclibcgnueabihf/arm-training-linux-uclibcgnueabihf/sysroot hello

You should now see the classic: Hello world!

Congratulations! You've compiled your first ARM program with a toolchain you've created yourself!

We were excited mainly to to see what we could do as a team.

We decided to build a simple app that would take a users email address, and then on each email submitted, we would plant one tree.

Problems to solve along the way

Setting up the webserver

As much as this was a problem, I love System Operations. I enjoyed setting up the Linux machine, web server, database, and dev environment. There were a few hiccups (mostly problems I created myself), like permissions errors, github authentication setup. But these errors really just contributed to my education on this topic.

The API

I know what a REST API is, I understand it, but I had seldom used them.

We were calling the API using PHP, which was something I had to learn how to do. I struggled figuring this out, I kept getting errors. Eventually only to figure out that i spelled the URL wrong! Rookie mistake.

Conclusion

Overall, had a great time at the hackathon with my friends. Very mentally draining, but I'm super happy I experienced it.

My Contributions

• Set up LAMP server with one click linode marketplace
• Linux admin:
  • created new accounts for my teamates
  • symlinked folders for their dev purposes
  • Setup mysql users
  • fixed user problems
• Setting up mysql
• Had to add 2gb of swap space because PHP composer uses a load of ram
• Utilized the REST API, reading documentation, formatting request, etc

I'm not exactly sure why this interested me, but it might have something to do with my facination for critical infrastructure. Http servers like Apache and NGINX are critical backbones of the web as we know it, and having a general understanding of how they work seemed cool to me. Along with this, when I first had the idea suggested to me on a podcast I was listening to, it seemed like such an unreachable goal.

In my previous semester at university I took a Systems Programming course where we learned C, and the basics of interacting with the Linux kernel, which included basic socket programming with TCP sockets. With this knowledge, I felt armed and ready to finally build an HTTP server.

Getting started

I honestly didn't feel ready to jump directly into the project. Firstly, I didn't have an amazing understanding of the backbones of this project, mainly TCP and HTTP. I picked up this book, and worked through the first few exercises. These were a super small program that lists your machines outward facing IP addresses, a simple TCP server that will capitalize a string sent to it, and a TCP Client.

These were fun little programs to write and taught me a lot of fun C tricks, and how TCP works.

Writing the server

After prepping all the knowledge, this wasn't actually too hard. I wasn't aiming to build a competitor to Apache or anything, so this only handles simple GET requests, and returns 200, 400, 404, or 500 responses. (I also added 418, but that was just for fun 😊)

One issue I saw from the start was preventing a directory traversal exploit. Because the parser is simple, and will go to whatever directory supplied, a malicious actor could add ".." to the path, which will go up a directory, and traverse to directories which they should not have access to, and potentially see things they shouldn't. the way I prevented this (Although likely not bulletproof) was to check for ".." at the front of the string, and return a 400 response.

My least favourite thing about writing in C is dealing with strings. Whenever I work with strings in PHP or Python, I feel so darn spoiled. When I work with C, I feel like jumping off a cliff. luckily, building the 200 response was only slightly annoying in this respect. There is always going to be at least one segmentation fault.

Closing

Overall this was a fun project and I learned a lot. This was a bucket list item for me so I'm happy to finish it up!

https://github.com/billvanleeuwen424/HTTPServer