English | Français
A Hardware Abstraction Layer for porting UGREEN NASync NAS devices (DXP series) to FreeBSD/ZFS, with the long-term goal of contributing to both zVault and XigmaNAS rather than building a competing firmware from scratch.
|
Note
|
This repository is deliberately scoped narrowly: it is not a rewrite of a complete NAS firmware, but the documentation and porting work for the UGREEN-specific hardware (front/bay LEDs, sensors, buttons, watchdog) that neither zVault (a TrueNAS CORE fork) nor XigmaNAS know about natively. The core ( |
UGOS, the proprietary firmware shipped on UGREEN NASync NAS devices, is based on Linux/Debian. This project’s goals are:
-
Replace UGOS with a proven FreeBSD + ZFS stack, by building on existing distributions (zVault, a community fork of TrueNAS CORE, and XigmaNAS, a long-running FreeBSD/ZFS NAS project) rather than starting a firmware from scratch.
-
Precisely document UGREEN hardware (networking, storage, LEDs, buttons, supervision) from direct, reproducible observations — not assumptions.
-
Port the missing UGREEN-specific components to FreeBSD (first and foremost: the front/bay LED controller, driven over SMBus).
-
Publish the result as open source, with the ultimate goal of upstream contributions to both zVault and XigmaNAS.
Development and testing are carried out on a UGREEN NASync DXP2800 (Intel N100, 2 bays), chosen for simpler hardware support than the DXP4800 Plus (no Aquantia AQC113 network controller, whose FreeBSD driver is still immature). See docs/hardware-notes.adoc for the detailed hardware findings.
Sprint 0 is complete: the repository is public, the SMBus protocol of the LED controller is fully reverse-documented, and contact has been established with the zVault team (Community#37).
A first userland utility (src/cli/ugreen-led-ctl) exists, builds, and has now been exercised on a real DXP2800 (under Linux, as a proving ground ahead of FreeBSD). Reading LED state is validated with certainty: a real 11-byte frame was captured from the chip and its checksum verified independently, byte for byte. Writing is not yet working: neither our own code nor the original upstream reference tool, compiled and run on the same unit, can make a write stick — a mystery not yet resolved, cross-referenced with a matching report on different (AMD-based) hardware in the upstream project’s issue tracker. See docs/journal.adoc and docs/protocol-i2c-leds.adoc for the full account. Validating the driver under FreeBSD/zVault remains the next milestone (sprint 3.3).
|
Note
|
The detailed technical documentation under |
| Path | Contents |
|---|---|
|
Raw hardware findings, model by model (chipsets, buses, observed Linux drivers, FreeBSD equivalents). |
|
Complete, reverse-engineered specification of the UGREEN LED controller’s SMBus protocol, with a FreeBSD porting skeleton. |
|
Dated log of observations, decisions, and milestones. |
|
Reference project plan: phases, sprints, architecture, risks. |
|
Comparison catalogue of available UGREEN NAS models, used to plan hardware purchases. |
|
Ready-to-publish outreach messages for the zVault and XigmaNAS communities, with their delivery status. |
|
Field checklist to work through in front of the NAS: readings to take, commands to run, and an error-reading grid for the first LED driver attempt. |
|
Bringing up the WiFi bridge (GL.iNet Flint) that connects the test NAS to the network, and SSH access from the workstation. |
|
The HAL core: FreeBSD userland utilities in C, knowing only |
|
Thin per-distribution integration layers ( |
|
Local FreeBSD build bench (QEMU, amd64). Compiles |
|
Supporting tooling, written in Crystal or shell: |
|
Automated tests (upcoming). |
|
Continuous integration on FreeBSD (via |
|
Pointer file for Claude Code (project context lives in the AsciiDoc docs above). |
The HAL core (src/cli/) is written in C, and deliberately so: it is meant to be proposed upstream to FreeBSD, zVault and XigmaNAS, whose base systems and review processes are C. A kernel-side driver, should one become necessary, could not be written in anything else.
Supporting tooling that runs on the developer’s machine (scripts/) is written in Crystal where it earns its keep, and in shell otherwise. Crystal is available on FreeBSD (lang/crystal), but shipping a language runtime onto a NAS appliance to drive four LEDs would be disproportionate, and would close the door on upstream contribution.
BSD-2-Clause — see LICENSE.
See CONTRIBUTING.adoc.