README
¶
FFOS-USER - Component and User Data Repository
Overall State
| Component | Build Status | Lint Status | Code Coverage |
|---|---|---|---|
| feral-controld | |||
| feral-setupd | |||
| feral-sys-monitord | |||
| feral-watchdog |
Architecture Overview
FFOS-USER provides components and user data to the FFOS build system. Build orchestration lives in the FFOS repo, while this repo focuses on component source and user data. CI workflows here run tests and lint only.
┌───────────────────────────────────────────────────────────┐
│ ffos-user Repository │
│ │
│ ┌──────────────────┐ ┌─────────────────┐ │
│ │ components/ │ │ users/ │ │
│ │ │ │ │ │
│ │ ┌──────────────┐ │ │ ┌─────────────┐ │ │
│ │ │feral-controld│ │ │ │ feralfile │ │ │
│ │ │feral-setupd │ │ │ │ soaktest │ │ │
│ │ │feral-sys- │ │ │ │ │ │ │
│ │ │ monitord │ │ │ │ Configs │ │ │
│ │ │feral-app- │ │ │ │ Scripts │ │ │
│ │ │ monitord │ │ │ │ Data │ │ │
│ │ │feral-watchdog│ │ │ └─────────────┘ │ │
│ │ │launcher-ui │ │ │ │ │
│ │ │player-wrapper│ │ │ │ │
│ │ │ -ui │ │ │ │ │
│ │ └──────────────┘ │ │ │ │
│ └──────────────────┘ └─────────────────┘ │
└───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────┐
│ ffos Build │
│ Repository │
└─────────────────┘
Repository Structure
ffos-user/
├── components/ # Service components
│ ├── feral-controld/ # Connection daemon
│ │ ├── main.go
│ │ ├── go.mod
│ │ └── ...
│ ├── feral-setupd/ # Setup daemon (Rust)
│ │ ├── src/
│ │ ├── Cargo.toml
│ │ └── ...
│ ├── feral-sys-monitord/ # System monitoring
│ ├── feral-watchdog/ # System watchdog
│ ├── launcher-ui/ # Launcher UI components
│ └── player-wrapper-ui/ # Player wrapper UI
└── users/ # User data and configurations
├── feralfile/ # feralfile user data
│ ├── scripts/ # User scripts
│ │ ├── start-kiosk.sh
│ │ ├── feral-updater.sh
│ │ └── ...
│ ├── .config/ # User configurations
│ │ │ ├── systemd/user/
│ │ │ │ ├── feral-sys-monitord.service
│ │ │ │ ├── feral-setupd.service
│ │ │ │ ├── chromium-kiosk.service
│ │ │ │ └── ...
│ │ ├── controld.json
│ │ └── watchdog.json
│ ├── .bash_profile # Shell configuration
│ └── ...
└── soaktest/ # soaktest user data
├── scripts/ # Test scripts
├── logs/ # Test logs
├── files/ # Test files
└── ...
Component Architecture
Service Components Layer
1. Connection Layer (feral-controld)
- Purpose: Manages device connectivity and communication
- Language: Go
- Dependencies: WebSocket, HTTP, CDP
- Build Output:
feral-controld-{version}-x86_64.pkg.tar.zst
2. Setup Layer (feral-setupd)
- Purpose: Handles device initialization and configuration
- Language: Rust
- Dependencies: Bluetooth, WiFi, System APIs
- Build Output:
feral-setupd-{version}-x86_64.pkg.tar.zst
3. Monitoring Layer
- feral-sys-monitord: System resource monitoring
- feral-watchdog: System watchdog and recovery
4. UI Layer
- launcher-ui: Main launcher interface
- player-wrapper-ui: Media player wrapper interface
User Data Layer
feralfile User
users/feralfile/
├── scripts/ # System scripts
│ ├── start-kiosk.sh # Kiosk mode startup
│ ├── feral-updater.sh # System update
│ ├── log-rotation.sh # Log management
│ └── ...
├── .config/ # Application configs
│ ├── systemd/user/ # Systemd services
│ │ ├── feral-sys-monitord.service
│ │ ├── feral-setupd.service
│ │ ├── chromium-kiosk.service
│ │ └── ...
│ ├── controld.json # Connection daemon config
│ └── watchdog.json # Watchdog config
└── .bash_profile # Shell environment
soaktest User
users/soaktest/
├── scripts/ # Test automation
│ └── soak-test.sh # Soak testing
├── logs/ # Test output
├── files/ # Test assets
└── .bash_profile # Test environment
Data Flow Architecture
Component Development Flow
Developer → ffos-user/components/ → ffos build process → R2 Storage
User Data Integration Flow
ffos-user/users/feralfile/ → ISO /home/feralfile/
ffos-user/users/soaktest/ → ISO /home/soaktest/ (conditional)
Configuration Propagation
ffos-user/users/feralfile/.config/ → ISO /home/feralfile/.config/
ffos-user/users/feralfile/scripts/ → ISO /home/feralfile/scripts/
Integration with FFOS
Version Control
- FFOS references specific ffos-user commits/tags
- Enables reproducible builds
- Supports multiple component versions
Build Integration
- FFOS checkout ffos-user at specified reference
- Builds components from source
- Merges user data into ISO
Data Synchronization
ffos-user/main → ffos build → R2/{main}/
ffos-user/develop → ffos build → R2/{develop}/
Repository Management
Commit Guidelines
- Use conventional commit format
- Prefix with component name for clarity
- Example:
feral-controld: add heartbeat functionality
Setup Instructions
No GitHub Actions Required
This repository is purely for source code and data. All build logic is handled by the FFOS repository.
Sync components to a device (dev)
Use the component sync helpers to push local changes to an FF1 over SSH (key-based).
# Default host + key
make -C components sync-feral-controld
# Override host or key
REMOTE_HOST=ff1-03vdu3x1.local REMOTE_KEY=~/.ssh/id_ed25519 make -C components sync-feral-controld
Click to show internal directories.
Click to hide internal directories.