PixelNAS firmware

This repository contains Device Tree overlays and customization scripts for building an Armbian image tailored for the PixelNAS mobile storage device.

The Device Tree sources in this project are based on the rk3568-roc-pc project. This provides a solid foundation for enabling various hardware interfaces on the AIO-3568J platform and custom module with 5x M.2 SATA or 4x M.2 SATA and integrated UPS.

These files enable various hardware interfaces and provide a custom SSH login banner. They are designed to be used with Armbian's build system, specifically via the customize-image.sh hook.

File Descriptions

Device Tree Overlays (.dts files)

Each overlay activates a specific hardware interfac. These overlays extend the base device tree with PixelNAS-specific functionality. Place these files in the Armbian build overlay directory.

File	Purpose
pixelnas-exp.dts	GPIO expander
pixelnas-gpio-butt.dts	GPIO‑connected buttons
pixelnas-i2c.dts	I2C bus
rk3568-sata-fbs.dts	SATA new kernel support

Customization Script

• customize-image.sh – This script is executed automatically during the Armbian build process. It copies the overlays to the appropriate directories, enables them, and installs the custom SSH banner.

SSH Login Banner

• 10-header – A text file (e.g., an ASCII logo or welcome message) displayed when users log in via SSH. It is installed by customize-image.sh into /etc/update-motd.d/.

How to Use These Files with Armbian Build

Follow the official Armbian user customization guide for detailed instructions.

File Placement Before Building

1. Overlay .dts files
   Place all .dts overlay files in the userpatches/overlay directory of your Armbian build tree.

2. customize-image.sh
   Place customize-image.sh in the root of the userpatches directory (i.e., userpatches/customize-image.sh). Make sure it is executable (chmod +x).

3. 10-header (SSH banner) – you have two options:

Option A (automatic copy via overlay structure)
Place the file maintaining the target filesystem path inside userpatches/overlay/:

   userpatches/overlay/etc/update-motd.d/10-header

Armbian will automatically copy the whole tree into the final image, so no extra commands are needed.

Option B (explicit copy in customize-image.sh)
Place 10-header directly in userpatches/overlay/ (flat) and add a copy command to your customize-image.sh:

cp /tmp/overlay/10-header /etc/update-motd.d/

(The /tmp/overlay directory contains the contents of userpatches/overlay during the build.)

Example Directory Structure (Option A)

userpatches/
├── customize-image.sh
└── overlay/
    ├── pixelnas-exp.dts
    ├── pixelnas-gpio-butt.dts
    ├── pixelnas-i2c.dts
    ├── rk3568-sata-fbs.dts
    └── etc/
        └── update-motd.d/
            └── 10-header

Build Example

To build an image including these overlays, run from the Armbian build root:

./compile.sh build BOARD=pixelnas BRANCH=current BUILD_DESKTOP=no BUILD_MINIMAL=no KERNEL_CONFIGURE=no RELEASE=trixie

To build the image with Openmediavault:

• place omv extension to /extensions
• add ENABLE_EXTENSIONS=omv to directive and run:

./compile.sh build BOARD=pixelnas BRANCH=current BUILD_DESKTOP=no BUILD_MINIMAL=no KERNEL_CONFIGURE=no RELEASE=trixie ENABLE_EXTENSIONS=omv

The customize-image.sh script will be called automatically during the finalization stage and will apply all customizations.

Some RAID tests

№	Configuration	RAID	fs	FBS	NCQ	Write (MiB/s)	Read (MiB/s)
1	no FBS	mdadm RAID10	ext4	off	off	24,3	1389
2	FBS, NCQ on	Btrfs RAID10	btrfs	on	on	97,4	1111
3	FBS, NCQ off	Btrfs RAID10	btrfs	on	off	97,5	820
4	RAID6 (5 ssd)	mdadm RAID6	ext4	on	on	151	833

Quick Guide: Updating U-Boot in Armbian Build

Edit board configuration Open config/boards/pixelnas.csc and set:

BOOTBRANCH_BOARD="tag:v2026.01"          # or branch:master
BOOTCONFIG="generic-rk3568_defconfig"

Remove any old UBOOT_CONFIG lines.

Clean cached U-Boot sources

rm -rf cache/git-bare/u-boot cache/sources/u-boot output/.artifacts/

Build the image - see the example above

Notes Verify that the chosen defconfig exists in the new U-Boot tree (you can check after first fetch:

ls cache/sources/u-boot/v2026.01/configs/ | grep <defconfig>).

If you encounter Git worktree errors, run

rm -rf cache/git-bare/u-boot cache/sources/u-boot

and retry...

Summary: Fixing SATA Performance on PixelNAS (RK3568)

The AHCI controller supports FBS (FIS‑based switching) but was not enabling it, causing severe performance degradation.

Two options:

- Legacy mode (no FBS) – disable NCQ to avoid instability.

• Add libata.force=noncq to /boot/armbianEnv.txt

- Enable FBS – requires a device‑tree overlay to set the FBS bit (bit 22, value 0x400000).

• Apply the overlay (via armbian-add-overlay or rebuild)
• NCQ can be kept enabled or disabled by force directive

dts
/dts-v1/;
/plugin/;
/ {
    fragment@0 {
        target-path = "/sata@fc800000";
        __overlay__ {
            #address-cells = <1>;
            #size-cells = <0>;
            sata-port@0 {
                reg = <0>;
                hba-port-cap = <0x400000>;
                phys = <&combphy2 1>;
                phy-names = "sata-phy";
                snps,rx-ts-max = <32>;
                snps,tx-ts-max = <32>;
            };
        };
    };
};

Universal approach: Enable FBS and NCQ by default in the image; NCQ can be turned off with the simple kernel parameter if needed.

Resources

https://pixelnas.com

License

This project is licensed under GPL-2.0 (consistent with Armbian). The base device tree sources are derived from the mainline Linux kernel rk3568-roc-pc.dts.