---
title: "Beryllium OS Micro: A Modular CircuitPython Environment with W5500 Ethernet"
url: "https://maker.wiznet.io/Grace_Koo/projects/micro/"
markdown_url: "https://maker.wiznet.io/Grace_Koo/projects/micro/md"
type: "UCC: User Created Content"
author: "beryllium-org"
author_url: "https://github.com/beryllium-org/Micro"
editor: "WIZnet"
editor_url: "https://maker.wiznet.io/"
original_author: "beryllium-org"
original_url: "https://github.com/beryllium-org/Micro"
published: "2026-08-19"
language: "en"
hardware: ["WIZnet W5500"]
likes: 0
views: 112
comments: 0
source: "WIZnet Makers (https://maker.wiznet.io/)"
---

# Beryllium OS Micro: A Modular CircuitPython Environment with W5500 Ethernet

> Beryllium OS Micro treats W5500 as a CircuitPython OS network driver, enabling modular wired Ethernet on small MCUs.

Original author: beryllium-org (source: https://github.com/beryllium-org/Micro)

## Components

- **WIZnet W5500** x 1 ([docs](https://docs.wiznet.io/Product/Chip/Ethernet/W5500))

WIZnet parts: W5500 ([Datasheet](https://docs.wiznet.io/Product/Chip/Ethernet/W5500/datasheet?utm_source=maker&utm_medium=project&utm_campaign=w5500), [product hub](https://maker.wiznet.io/products/w5500/))

## Article

## Beryllium OS Micro: Integrating W5500 Ethernet into a CircuitPython OS

### Summary

[Beryllium OS Micro](https://github.com/beryllium-org/Micro), formerly known as ljinux, is a Unix-like operating environment for CircuitPython-powered microcontrollers. It is not a Linux distribution and cannot run Linux binaries. Instead, it provides an OS-style shell, device model, package manager, board configuration, and Python execution environment on small MCUs.

The project includes a dedicated W5500 SPI Ethernet driver at [`drivers/w5500spi.py`](https://github.com/beryllium-org/Micro/blob/cb949648ad40bca63d78a62fe00fc1f6312e0e58/drivers/w5500spi.py). This is interesting because it attempts to make W5500 Ethernet a managed OS network interface rather than just a library used by one application.

| Item | Verified detail |
| --- | --- |
| Runtime | CircuitPython 9.0.x, 9.1.x, and 9.2.x |
| Supported MCU families | ESP32, RP2040/RP2350, nRF52840, and SAMD51 |
| W5500 driver | `drivers/w5500spi.py` |
| MCU connection | SPI using MOSI, MISO, SCLK, and CS |
| W5500 role | Wired Ethernet interface and hardware TCP/IP controller |
| Project status | Early development; Kernel APIs are still changing |

The README estimates that roughly 70 KB of usable RAM is required, while the porting guide recommends at least 100 KB of free RAM. The actual memory budget should therefore be checked on each target board.

### Why Beryllium OS Micro Is Useful

Beryllium OS Micro gives a CircuitPython board a more organized way to run commands, drivers, packages, and application scripts.

| Feature | What it means |
| --- | --- |
| Unix-like workflow | Use a serial console to run commands and work with files and modules. |
| Modular drivers | Load hardware features, such as W5500 Ethernet, as reusable drivers. |
| Package management | Add optional software packages through JPKG instead of copying every feature manually. |
| Board-specific configuration | Keep pin maps, drivers, and package lists separate for each supported board. |
| Lightweight runtime | Designed for small CircuitPython boards, with about 70 KB of usable RAM as a minimum guideline. |
| Multi-board support | Uses a similar workflow across supported ESP32, RP2040/RP2350, nRF52840, and SAMD51 boards. |

In simple terms, CircuitPython usually runs one main Python program on a board. Beryllium OS Micro adds a command environment, file structure, driver-loading method, and package rules around that program.

```plaintext
Typical CircuitPython project
One main application file
 ├─ Ethernet setup
 ├─ Sensor code
 ├─ Display code
 └─ Application logic

Beryllium OS Micro
OS environment
 ├─ Board configuration
 ├─ Reusable drivers
 ├─ Optional packages
 ├─ Diagnostic commands
 └─ Application scripts
```

This can make development easier when a project grows beyond a single experiment. Instead of rewriting Ethernet setup, pin definitions, and utility code for every application, developers can keep those functions as reusable system components.

### How W5500 Fits Into the OS

The project includes a W5500 SPI driver that is intended to be loaded as a network module.

```plaintext
Beryllium OS Micro
        │
        │ loads the w5500spi driver
        ▼
CircuitPython WIZNET5K library
        │
        │ SPI: MOSI, MISO, SCLK, and CS
        ▼
W5500 hardware TCP/IP controller
        │
        ▼
Wired Ethernet network
```

The W5500 driver initializes the SPI interface, detects the W5500, and checks the Ethernet link status. Its intended role is to make wired Ethernet available to the OS as a reusable network function, rather than as code used by only one application.

### Why This Helps in Practice

| Development task | Why the OS-style structure helps |
| --- | --- |
| Ethernet bring-up | Check pin mapping, SPI setup, W5500 detection, and link status step by step. |
| Prototype development | Reuse network, sensor, display, and utility modules across projects. |
| Board-port development | Keep board-specific pin maps and driver lists separate from application code. |
| Diagnostics | Use console commands, logs, and memory information without rebuilding a large application. |
| Learning and maker projects | Combine Python scripts, hardware drivers, and Ethernet functions in one organized environment. |

Micro is still an early-stage project, so this structure should be viewed as a useful development and integration model rather than a production-ready embedded OS.

### What the current W5500 driver does

The W5500 driver imports `adafruit_wiznet5k`, creates an SPI bus and chip-select pin, then initializes a `WIZNET5K` interface.

```plaintext
self._cs = DigitalInOut(cs)
self._spi = SPI(clock=sclk, MOSI=mosi, MISO=miso)
self._interface = WIZNET5K(self._spi, self._cs, is_dhcp=dhc)
self._interface.detect_w5500()
```

The `connect()` function accepts:

```plaintext
mosi, miso, sclk, cs, ip, subnet_mask, gateway, dns, hostname, debug
```

It then performs these steps:

1. Creates the SPI and chip-select interfaces.

2. Initializes the W5500 interface.

3. Detects the W5500 chip.

4. Checks `link_status`.

5. Calls DHCP handling after a successful link check.

6. Returns status `0` on completion, `1` for a runtime error, `2` when the Ethernet link is missing, and `3` when required address arguments are incomplete.

The driver identifies itself as:

```plaintext
self.hw_name = "w5500"
self.interface_type = "ethernet"
```

This makes the intended role of W5500 clear: it is the wired Ethernet interface for Beryllium OS.

### Current limitations and integration tasks

The project is more valuable as an early Ethernet OS-integration case than as a finished network stack. Several items need attention before it can be considered a complete W5500 platform.

| Area | Current state | Required work |
| --- | --- | --- |
| W5500 detection | The driver calls `detect_w5500()`. | The current `adafruit_wiznet5k` library performs chip detection in its constructor, and this old public call is no longer present. The driver should be updated. |
| DHCP | The driver passes `response_timeout=10` to `set_dhcp()`. | The current library exposes `set_dhcp(hostname=...)`; the obsolete keyword should be removed. |
| Static IP and DHCP | Static address parameters are processed, but the following link branch also calls DHCP. | Static-IP and DHCP behavior should be separated and tested on hardware. |
| Higher-level networking | `ping()`, `get()`, `resolve()`, `scan()`, `start()`, `stop()`, and `resetsock()` are incomplete or return `None`. | DNS, HTTP, NTP, IP information, and socket handling need implementation. |
| Installation | `copy_w5500spi.py` still references older `other/` paths. | The installer should be aligned with the current driver and dependency locations. |
| Board integration | None of the current 39 `Boardfiles/*/drivers.txt` entries preload W5500. | Add a W5500 board port and include the driver and its dependencies by default. |

The generic device model is already present, but the exact W5500 module-load command should be verified on hardware: the driver class is named `driver_w5500spi`, while its usage comment refers to `w5500spi`.

### A practical target: W5500-EVB-Pico

CircuitPython already defines a `wiznet_w5500_evb_pico` board target. Its W5500 SPI pins map directly to the arguments expected by Beryllium OS’s driver.

| CircuitPython pin | RP2040 GPIO | Driver argument |
| --- | --- | --- |
| `board.W5K_MOSI` | GPIO19 | `mosi` |
| `board.W5K_MISO` | GPIO16 | `miso` |
| `board.W5K_SCK` | GPIO18 | `sclk` |
| `board.W5K_CS` | GPIO17 | `cs` |

The board also exposes `W5K_RST` on GPIO20 and `W5K_INT` on GPIO21. The current Beryllium OS driver does not use those signals. Adding reset support would improve Ethernet recovery, while interrupt support could reduce polling.

A useful next step would be a dedicated W5500-EVB-Pico Boardfile containing:

- Board LED settings

- Pinout map

- W5500 driver entry

- Updated `adafruit_wiznet5k` dependencies

- A verified DHCP test

- A verified static-IP test

- DNS, HTTP, and NTP validation

### Suitable applications

| Application | Why Beryllium OS Micro is useful | What must be verified first |
| --- | --- | --- |
| Ethernet bring-up bench | Shell tools can inspect pins, logs, memory, and Ethernet link status interactively. | W5500 module loading, SPI configuration, DHCP, and static IP. |
| Education and maker labs | Combines shell commands, Python execution, GPIO, I2C, UART, package management, and Ethernet integration in one environment. | Board memory budget and CircuitPython version. |
| Sensor and instrumentation prototypes | The MCU can handle sensors and application logic while W5500 provides the wired network path. | DNS, HTTP, MQTT, and error-recovery functions. |
| Field debugging equipment | Serial console and OS commands are useful for local diagnosis and configuration. | Authentication, encryption, update policy, and network-access controls. |
| WIZnet board-port development | Provides a concrete structure for turning W5500 into a reusable OS network interface. | Driver maintenance and a validated W5500 Boardfile. |

### What it is not yet suited for

Beryllium OS Micro should not be presented as a production-ready industrial network OS today.

- The project describes itself as early development.

- Its Kernel APIs are changing.

- The W5500 driver has unfinished networking methods.

- The Wi-Fi management path can start an AP and Telnet service by default, so network-access settings must be reviewed before any real deployment.

- The manual does not guarantee strict process-variable isolation.

The best description is therefore:

> Beryllium OS Micro is an early but well-structured attempt to integrate W5500 Ethernet into a CircuitPython operating environment. It is strong as a learning, bring-up, and platform-development case; production use requires driver completion, validation, and security hardening.

### Related Projects on WIZnet Maker

[Ljinux](https://maker.wiznet.io/viktor/projects/Ljinux/)
An earlier Maker entry for the same project under its former name. This article differs by focusing on the W5500 driver architecture, current library compatibility, and the path toward a W5500-EVB-Pico board port.

[CircuitPython Wiznet5k: PR #178 Socket Reliability Update](https://maker.wiznet.io/Grace_Koo/projects/match-core-socket-behaviour/)
Covers the `adafruit_wiznet5k` library layer that Beryllium OS uses underneath its W5500 driver. Library behavior directly affects the driver’s future DHCP, DNS, HTTP, and socket implementation.

[How Does Pico 2W Use W5500 Ethernet for CircuitPython MQTT?](https://maker.wiznet.io/Benjamin/projects/how-does-pico-2w-use-w5500-ethernet-for-circuitpython-mqtt/)
Demonstrates W5500 use at the application level with CircuitPython and MQTT. Beryllium OS takes a different direction by attempting to expose the same Ethernet stack as an OS-managed network interface.

[How to Initialize W5500 Ethernet with CircuitPython on ESP32-S3?](https://maker.wiznet.io/mark/projects/how-to-initialize-w5500-ethernet-with-circuitpython-on-esp32-s3/)
A relevant reference for the SPI initialization and Ethernet bring-up stage, especially for ESP32-family boards supported by Beryllium OS.

### References

- [Beryllium OS Micro repository](https://github.com/beryllium-org/Micro)

- [Beryllium OS Manual](https://github.com/beryllium-org/Micro/blob/cb949648ad40bca63d78a62fe00fc1f6312e0e58/Manual.txt)

- [Beryllium OS W5500 driver](https://github.com/beryllium-org/Micro/blob/cb949648ad40bca63d78a62fe00fc1f6312e0e58/drivers/w5500spi.py)

- [Beryllium OS porting guide](https://github.com/beryllium-org/Micro/blob/cb949648ad40bca63d78a62fe00fc1f6312e0e58/PORTING.md)

- [CircuitPython W5500-EVB-Pico pin definition](https://github.com/adafruit/circuitpython/blob/main/ports/raspberrypi/boards/wiznet_w5500_evb_pico/pins.c)

- [Adafruit CircuitPython Wiznet5k library](https://github.com/adafruit/Adafruit_CircuitPython_Wiznet5k)

- [W5500 official documentation](https://docs.wiznet.io/Product/Chip/Ethernet/W5500)

---

Source: https://maker.wiznet.io/Grace_Koo/projects/micro/