Skip to content

Commit 7099da8

Browse files
dbozedboze
authored
add sensorbox docs (#81)
1 parent 7d51778 commit 7099da8

4 files changed

Lines changed: 194 additions & 0 deletions

File tree

‎docs/sensorbox/README.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
title: Sensorbox
3+
shortTitle: Sensorbox
4+
metaDescription: Sensorbox is a self-hosted system for building OpenWrt-based Orb sensor images. Pick a supported device, provide your Wi-Fi credentials, and get a ready-to-flash image that continuously monitors your network experience.
5+
section: sensorbox
6+
---
7+
8+
# Sensorbox
9+
10+
Sensorbox is a self-hosted system for building OpenWrt-based Orb sensor images. You run a small web app locally, pick a supported device, provide your Wi-Fi credentials, and customize your install. The result is an SD-card (or eMMC) image that boots into a dedicated, always-on Orb sensor — ready to continuously monitor your network experience.
11+
12+
<img src="../../images/sensorbox/configurator.png" alt="Sensorbox configurator UI" width="560" />
13+
14+
:::note
15+
Sensorbox is currently in **beta**.
16+
:::
17+
18+
## What you'll need
19+
20+
- A supported single-board computer or router (see the [NanoPi Zero2 hardware build](/docs/sensorbox/nanopi-zero2.md) for a worked example).
21+
- A computer to run Sensorbox and flash the resulting image. The setup below is written for macOS and Linux.
22+
- [Podman](https://podman.io/) and `podman-compose`. Sensorbox runs on Podman because ASU's build worker spawns one container per build via the Podman API — Docker is not a tested drop-in substitute.
23+
- An SD card (or eMMC) and a way to flash it: [Raspberry Pi Imager](https://www.raspberrypi.com/software/), [balenaEtcher](https://etcher.balena.io/), or `dd`.
24+
25+
## Step 1: Clone the repository
26+
27+
Sensorbox uses git submodules, so clone recursively:
28+
29+
```bash
30+
git clone --recurse-submodules git@github.com:orbforge/sensorbox.git
31+
```
32+
33+
If you already cloned without `--recurse-submodules`:
34+
35+
```bash
36+
git submodule update --init
37+
```
38+
39+
## Step 2: Install Podman
40+
41+
### macOS
42+
43+
1. Install Podman and the compose wrapper:
44+
45+
```bash
46+
brew install podman podman-compose
47+
```
48+
49+
An optional GUI is available with `brew install --cask podman-desktop`.
50+
51+
2. Initialize and start the Podman VM. The resource bumps matter — ASU's ImageBuilder runs will run out of memory or disk on the defaults:
52+
53+
```bash
54+
podman machine init --cpus 4 --memory 8192 --disk-size 100
55+
podman machine start
56+
podman info # sanity check
57+
```
58+
59+
:::note
60+
`--disk-size 100` is a VM ceiling, not preallocated storage. ASU upstream recommends 50 GB minimum, and caches grow over time.
61+
:::
62+
63+
3. After reboots or Podman upgrades, restart the VM:
64+
65+
```bash
66+
podman machine start
67+
```
68+
69+
### Linux
70+
71+
Install `podman` and `podman-compose` from your distribution, then enable the user socket so the ASU worker can reach it:
72+
73+
```bash
74+
systemctl --user enable --now podman.socket
75+
```
76+
77+
No VM is needed — Podman runs natively.
78+
79+
### Windows
80+
81+
Not yet validated. Podman Desktop supports Windows via WSL2; expect a flow similar to macOS.
82+
83+
## Step 3: Configure
84+
85+
Copy the example environment file:
86+
87+
```bash
88+
cp .env.example .env
89+
```
90+
91+
Edit two values in `.env`:
92+
93+
- **`PUBLIC_PATH`** — set to the absolute path of the `public` directory inside your clone, for example `/Users/<you>/<path-to>/sensorbox/public` on macOS or `/home/<you>/<path-to>/sensorbox/public` on Linux. Then create the subdirectories it expects:
94+
95+
```bash
96+
mkdir -p "$PUBLIC_PATH"/{store,logs}
97+
```
98+
99+
- **`CONTAINER_SOCKET_PATH`** — run the command below and paste the result (dropping the `unix://` prefix):
100+
101+
```bash
102+
podman info --format '{{.Host.RemoteSocket.Path}}'
103+
```
104+
105+
Leave everything else at its default.
106+
107+
## Step 4: Run the stack
108+
109+
From the repository root:
110+
111+
```bash
112+
podman-compose up -d
113+
```
114+
115+
Open <http://localhost:8080/> in your browser, select your device, and configure your install. The first run pulls the ASU image and builds the `openwrt-builder` image, which takes a few minutes. Subsequent runs are fast.
116+
117+
:::note
118+
Devices that aren't in the latest stable OpenWrt release have to be compiled from source, which can take a while for the initial build — around 35 minutes on an M1 MacBook Pro. After that, builds are fast.
119+
:::
120+
121+
When the build finishes, the download section provides flashing instructions specific to your device. You can flash the image with Raspberry Pi Imager, balenaEtcher, or `dd`. On macOS, there is a helper script at `scripts/flash-sd.sh`.
122+
123+
Tear the stack down when you're done:
124+
125+
```bash
126+
podman-compose down
127+
```
128+
129+
## Recipes
130+
131+
Sensorbox uses YAML "recipes" to power the web-based configurator, inject settings, install packages, and create scripts. See the recipes README in the repository for details on writing your own.
132+
133+
## Hardware builds
134+
135+
- [NanoPi Zero2](/docs/sensorbox/nanopi-zero2.md) — a small, low-cost dedicated sensor with optional eMMC storage and Wi-Fi 7.

‎docs/sensorbox/nanopi-zero2.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
title: NanoPi Zero2 Hardware Build
3+
shortTitle: NanoPi Zero2
4+
metaDescription: Build a small, low-cost dedicated Orb sensor from a FriendlyElec NanoPi Zero2, with an optional eMMC and Wi-Fi 7 upgrade.
5+
section: sensorbox
6+
layout: guides
7+
subtitle: 'Difficulty: Advanced 🛠️'
8+
---
9+
10+
# NanoPi Zero2 Hardware Build
11+
12+
This guide covers assembling a [FriendlyElec NanoPi Zero2](https://www.friendlyelec.com/index.php?route=product/product&product_id=304) into a small, low-cost dedicated Orb sensor. Once the hardware is assembled, build and flash an image for it with [Sensorbox](/docs/sensorbox).
13+
14+
## Why the NanoPi Zero2
15+
16+
The NanoPi Zero2 is a compact single-board computer that makes a capable always-on sensor:
17+
18+
- **1 GbE** Ethernet
19+
- **M.2 Key E** slot for an internal Wi-Fi card
20+
- **USB-C OTG**
21+
- Very small footprint
22+
23+
## Bill of materials
24+
25+
| Item |
26+
| --- |
27+
| Device + case (includes shipping) |
28+
| 64 GB eMMC (optional) |
29+
| **Wi-Fi 7 upgrade (optional):** |
30+
| Intel BE200 |
31+
| 6 GHz antennas |
32+
| 0.5 mm thermal pad |
33+
34+
The eMMC and Wi-Fi 7 upgrade are both optional. A basic build that relies on Ethernet or the stock wireless costs considerably less.
35+
36+
## Optional: Wi-Fi 7 upgrade
37+
38+
If you want Wi-Fi 7, you'll install an Intel BE200 card in the M.2 Key E slot. The stock antennas do not reliably support 6 GHz, so you'll also need new antennas. These have been tested and work: [Leankon dipole flex Wi-Fi 6E antennas](https://www.leankon.com/product/dipole-flex-bluetooth-wifi-6e-antenna/).
39+
40+
:::warning
41+
A **0.5 mm thermal pad** on the BE200 is required — don't skip it. The card needs the pad to transfer heat to the case and run reliably.
42+
:::
43+
44+
### Steps
45+
46+
1. Remove the stock antennas.
47+
2. Install the new 6 GHz antennas in the same locations.
48+
3. Install the Intel BE200 card in the M.2 Key E slot.
49+
4. Add the 0.5 mm thermal pad to the BE200.
50+
5. Route the antenna wires and attach them to the BE200.
51+
6. Close the case.
52+
53+
## Build the sensor image
54+
55+
With the hardware assembled, follow the [Sensorbox guide](/docs/sensorbox) to build and flash an OpenWrt-based Orb sensor image for the NanoPi Zero2. Select the NanoPi Zero2 in the configurator, provide your Wi-Fi credentials, and flash the resulting image to your SD card or eMMC.

‎images/sensorbox/configurator.png‎

765 KB
Loading

‎navigation.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,3 +78,7 @@
7878
- [API](/docs/integrations/api.md)
7979
- [Elgato Stream Deck](/docs/integrations/stream-deck.md)
8080
- [Hamina Live View](/docs/integrations/hamina.md)
81+
82+
## [Sensorbox](/docs/sensorbox)
83+
84+
- [NanoPi Zero2](/docs/sensorbox/nanopi-zero2.md)

0 commit comments

Comments
 (0)