Skip to main content

BLE, Network States & DRM Sysfs Interface Documentation

Admiral exposes a virtual sysfs interface to workload containers at /sys/admiral and the low-level platform interfaces on ARM development boards.

The architecture bridges the host-level Bluetooth/Network daemon with the users workoad, enabling zero-cost, lock-free IPC via read-only bind mounts of standard tmpfs assets.

1. Workload Container Interface: /sys/admiral​

Inside any running workload container, the system registers static device identification nodes and dynamic network status states at /sys/admiral.

Directory Tree Overview​

/sys/admiral/
├── device_id                       # Cryptographically unique hardware identity
├── fleet_id                        # Bound Fleet UUID
├── org_id                          # Bound Organization UUID
└── bluetooth/                      # Live Bluetooth & Network states (Preserved Inodes)
    ├── advertising                 # 'true' | 'false' (BLE Setup Advertisements)
    ├── ident                       # Dynamic screen-friendly BLE name (e.g., ADM-QWERT123)
    ├── link_type                   # Comma-separated active links (e.g., wifi,ethernet)
    ├── network_status              # 'connected' | 'connecting' | 'disconnected'
    ├── pairing_status              # 'unprovisioned' | 'configuring' | 'paired' | 'fully_provisioned'
    └── prov_state                  # Raw state machine byte as integer enum (0 to 4, or 255)

2. Dynamic State Nodes (/sys/admiral/bluetooth/*)​

These virtual files are updated atomically on the host inside /var/run/admrl/state/bluetooth using in-place truncation (O_TRUNC). This preserves file inodes, allowing containerized processes to watch these files using inotify (e.g., IN_MODIFY) without breaking the file listener when a write occurs.

File Reference​

ident​

  • Format: Plaintext String (ADM-[BASE32_HASH])
  • Description: The unique 8-character Base32 alphanumeric identifier generated from 5 bytes of entropy derived from the board’s hardware serial number. Matches the broadcast legacy local name in BLE advertisement packets.

advertising​

  • Format: Plaintext Boolean (true or false)
  • Description: Declares if the BLE Provisioning GATT server is actively transmitting setup beacons. Transitions to false automatically when the device enters a fully provisioned state or times out.

prov_state​

  • Format: String Integer (0, 1, 2, 3, 4, or 255)
  • Description: Reflects the internal raw state engine value defined by the BLE service capability:
    • 0: Unprovisioned (Waiting for first secure pairing key or Wi-Fi credential)
    • 1: Wi-Fi Configured (Host accepted credentials and is attempting handshake)
    • 2: Wi-Fi Connected (Handshake success, waiting for DHCP context)
    • 3: Cloud Paired (Ephemeral X25519 secure tunnel active, cloud pairing token acquired)
    • 4: Fully Provisioned (WPA Supplicant credentials sealed, BLE shutdown initiated)
    • 255: Error State (See GATT error register)

pairing_status​

  • Format: Plaintext String Enumeration
  • Description: Human-readable mapping of the active provisioning step:
    • unprovisioned
    • configuring
    • paired
    • fully_provisioned

network_status​

  • Format: Plaintext String Enumeration
  • Description: Mapped network status derived from active link detection:
    • disconnected: No IP interface is bound to the routing tables.
    • connecting: Interfaces are up but negotiating details with a DHCP server.
    • connected: Real, routable IP addresses successfully assigned.
  • Format: Plaintext comma-separated String
  • Description: Identifies physical physical links currently provisioned with active unicast routing.
    • Values: none, wifi, ethernet, cellular, or combinations such as wifi,ethernet.

3. ARM Dev Board Custom HW Interface​

Specific ARM development boards running the customized Admiral Kernel expose low-level handles for physical screen buffer plane multiplexing.

Hardware Splash Controller​

  • Node Path: /sys/class/drm/card0/splash_enable
  • Permission: Write-Only / Read-Write (Host/Kernel context)
  • Values:
    • 0: Disabled / Off. Yields the primary display controller plane (CRTC) and framebuffers back to standard DRM/KMS userspace processes (e.g., custom UI engines, Wayland compositors, or TUI outputs).
    • 1: Enabled / On. Actively locks the display plane to render the boot splash screen from early RAM-disk or kernel image space, preventing boot tty text or raw console logs from bleeding onto physical panels during workload initialization or restarts.
# Example: Instantly release boot splash to expose workload TUI/UI output
echo 0 > /sys/class/drm/card0/splash_enable

# Example: Enforce display shielding during dynamic workload container hot-reloads
echo 1 > /sys/class/drm/card0/splash_enable

4. Integration Guide & Watcher Patterns​

Because these sysfs nodes are written atomically with inode preservation, workload microservices can efficiently track state mutations using system-level asynchronous change notification mechanisms rather than execution-expensive polling loops.

Bash / Shell Integration​

To execute triggers whenever the platform network status shifts inside a containerized script:

#!/bin/sh
STATE_FILE="/sys/admiral/bluetooth/network_status"

echo "Current Status: $(cat $STATE_FILE)"

# Efficient blocking watch on the inode using inotifywait
while inotifywait -e modify "$STATE_FILE"; do
    NEW_STATE=$(cat "$STATE_FILE")
    echo "Network state changed to: $NEW_STATE"
    if [ "$NEW_STATE" = "connected" ]; then
        # Trigger internal service registration
        /app/register_workload.sh
    fi
done

Go Integration​

An idiomatic implementation inside a Go-based workload:

package main

import (
	"log"
	"os"

	"github.com/fsnotify/fsnotify"
)

const TargetNode = "/sys/admiral/bluetooth/pairing_status"

func main() {
	watcher, err := fsnotify.NewWatcher()
	if err != nil {
		log.Fatalf("Failed to initialize fsnotify: %v", err)
	}
	defer watcher.Close()

	err = watcher.Add(TargetNode)
	if err != nil {
		log.Fatalf("Failed to register watch path: %v", err)
	}

	log.Println("Monitoring pairing status transitions...")
	for {
		select {
		case event, ok := <-watcher.Events:
			if !ok {
				return
			}
			if event.Has(fsnotify.Write) {
				data, err := os.ReadFile(TargetNode)
				if err == nil {
					log.Printf("Pairing State updated: %s", string(data))
				}
			}
		case err, ok := <-watcher.Errors:
			if !ok {
				return
			}
			log.Printf("Watcher Error context: %v", err)
		}
	}
}