diff --git a/docs/quick-start-hardware/img/rpi-kit-unopened.jpg b/docs/quick-start-hardware/img/rpi-kit-unopened.jpg new file mode 100644 index 0000000..c9dc62c Binary files /dev/null and b/docs/quick-start-hardware/img/rpi-kit-unopened.jpg differ diff --git a/docs/quick-start-hardware/img/vilros-kit-opened.jpg b/docs/quick-start-hardware/img/vilros-kit-opened.jpg new file mode 100644 index 0000000..a535c72 Binary files /dev/null and b/docs/quick-start-hardware/img/vilros-kit-opened.jpg differ diff --git a/docs/quick-start-hardware/index.md b/docs/quick-start-hardware/index.md new file mode 100644 index 0000000..0b7a0db --- /dev/null +++ b/docs/quick-start-hardware/index.md @@ -0,0 +1,16 @@ +--- +sidebar_position: 5 +title: Quick Start - Hardware +--- + +A step-by-step guide for running Ambrosia on a single-board computer (SBC). Three audiences share this section: + +1. **DIY — Raspberry Pi Zero 2W** — you have parts and want to set up an RPi from scratch. + - [Raspberry Pi setup](./rpi-setup.md) — flash, boot, SSH + - [Install Ambrosia on Raspberry Pi](./rpi-install.md) — native or Docker +2. **DIY — OrangePi Zero 2W** — you have parts and want to set up an OPi from scratch. + - [OrangePi setup](./opi-setup.md) — flash, boot, SSH (then [Install Ambrosia](./rpi-install.md)) +3. **Preinstalled** — you received a configured device and just want to use it. + - [Take your Ambrosia unit home](./preinstalled.md) — first-boot Wi-Fi setup (English + Spanish) + +The DIY flows today are manual. The longer-term goal is a single command that produces a verifiable reproducible image you flash to an SD card — see the [`hardware/`](https://github.com/olympus-btc/ambrosia/tree/main/hardware) tree in the main repo for status. diff --git a/docs/quick-start-hardware/opi-setup.md b/docs/quick-start-hardware/opi-setup.md new file mode 100644 index 0000000..e983017 --- /dev/null +++ b/docs/quick-start-hardware/opi-setup.md @@ -0,0 +1,292 @@ +--- +title: "OrangePi Zero 2W setup" +sidebar_position: 3 +slug: /quick-start-hardware/opi-setup +--- + +Setting up an OrangePi Zero 2W from scratch, ready to run Ambrosia. + +## What You'll Need + +**Board & kit:** +- OrangePi Zero 2W (1GB model or higher) +- Case with HDMI/USB breakout (e.g. Argon POD Kit) — optional but convenient +- USB-C power supply (5V/3A recommended) + +**Sold separately:** +- microSD card — 32GB or larger (SanDisk Ultra works well) +- A computer with a microSD card reader (to flash the OS) + +**Network (pick one):** +- **Ethernet (recommended):** USB-C to Ethernet adapter + Ethernet cable, plugged into your router +- **Wi-Fi:** works too, but requires HDMI monitor + USB keyboard for the initial Wi-Fi config since the OrangePi Debian image has no pre-boot config wizard + +**Software (on your computer):** +- `p7zip-full` to extract the image archive +- `dd` (built in on Linux/macOS) or [balenaEtcher](https://etcher.balena.io/) for flashing + +--- + +## Step 1: Download the Debian image + +Grab the official Debian 12 Bookworm **server** image (CLI only — no desktop, smallest footprint for the 1GB board) from the [OrangePi Zero 2W download page](http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-Zero-2W.html). + +Scroll to the Debian section and download from the Google Drive mirror. The file is named something like: + +``` +Orangepizero2w_1.0.2_debian_bookworm_server_linux6.1.31.7z +``` + +--- + +## Step 2: Extract and verify + +```bash +cd ~/Downloads +sudo apt install -y p7zip-full # if 7z is not installed +7z x Orangepizero2w_1.0.2_debian_bookworm_server_linux6.1.31.7z +``` + +You should get two files: +- `*.img` — the disk image (~2.4GB) +- `*.img.sha` — sha256 checksum + +Verify the image matches the checksum: + +```bash +sha256sum -c Orangepizero2w_1.0.2_debian_bookworm_server_linux6.1.31.img.sha +``` + +Expected output: `...img: OK` + +--- + +## Step 3: Flash the SD card + +Insert the microSD card into your computer, then find its device name: + +```bash +lsblk -d -o NAME,SIZE,MODEL,TRAN +``` + +Look for the card by size (e.g. `29.7G` for a 32GB card). The `TRAN` column will usually show `usb` for an external reader. **Double-check** — flashing the wrong device will destroy your system disk. + +Unmount any auto-mounted partitions, then flash: + +```bash +sudo umount /dev/sdX* # replace sdX with your card's device +sudo dd if=~/Downloads/Orangepizero2w_1.0.2_debian_bookworm_server_linux6.1.31.img of=/dev/sdX bs=4M conv=fsync status=progress +sync +sudo eject /dev/sdX +``` + +Flashing takes ~1-2 minutes on a decent card. + +--- + +## Step 4: Boot the OrangePi + +The Zero 2W has two USB-C ports labeled **USB0** and **USB1**: + +- **USB0** = OTG (device/host) — defaults to device mode in the OrangePi Linux image +- **USB1** = host-only + +Recommended layout: + +1. Insert the microSD card into the OrangePi. +2. Plug your **USB-C to Ethernet adapter into USB1** and connect the Ethernet cable to your router. +3. Plug the **power supply into USB0**. + +The board boots headlessly — no HDMI or keyboard needed if you're going over Ethernet. First boot takes ~30-60 seconds. + +--- + +## Step 5: Find the OrangePi's IP address + +:::caution +The official OrangePi Debian image does **not** ship with `avahi-daemon`, so `orangepizero2w.local` won't resolve out of the box. You need the IP. +::: + +### If you plugged into your router + +Check your router's DHCP lease page for a host named `orangepizero2w`. + +### If you went direct laptop → OrangePi (connection sharing) + +On GNOME, set your Ethernet connection's IPv4 method to **"Shared to other computers"** (Settings → Network → click the ⚙ next to the wired connection → IPv4). The laptop then hands out DHCP on `10.42.0.0/24`. + +Find the OrangePi's IP by scanning for the Realtek MAC (the USB Ethernet adapter reports as Realtek): + +```bash +sudo nmap -sn 10.42.0.0/24 +``` + +Look for a host with a Realtek MAC — that's the board. Note the IP (e.g. `10.42.0.76`). + +--- + +## Step 6: SSH into the OrangePi + +```bash +ssh root@ +``` + +Default password: `orangepi` + +The image does **not** run a first-login wizard — you'll drop straight into a root shell. You need to lock it down manually. + +--- + +## Step 7: Change the root password and create your user + +As root on the OrangePi: + +```bash +passwd +``` + +Pick a strong password — you won't use root often after this, but don't leave it on the default. + +Create a regular user for yourself, add them to `sudo`: + +```bash +adduser +usermod -aG sudo +``` + +`adduser` will prompt for a password and some optional info (full name, phone, etc. — just press Enter through these). + +--- + +## Step 8: Remove the default `orangepi` user + +The image ships with a default `orangepi` user whose password is publicly documented — remove it now that you have your own account. + +Kill any lingering sessions (the image auto-logs-in `orangepi` on the serial and HDMI consoles) and delete the user: + +```bash +pkill -KILL -u orangepi +deluser --remove-home orangepi +``` + +--- + +## Step 9: Log out and SSH back in as your new user + +```bash +exit +ssh @ +``` + +--- + +## Step 10: Set a unique hostname + +Everyone on the same network needs a unique hostname. Pick something like `ambrosia-`: + +```bash +sudo hostnamectl set-hostname ambrosia- +sudo sed -i "s/127.0.1.1.*/127.0.1.1\tambrosia-/" /etc/hosts +``` + +--- + +## Step 11: Connect to Wi-Fi + +Do this **before** any `apt` commands — the shared-Ethernet tether from your laptop often has flaky outbound routing, and the image's default apt mirrors (Huawei Cloud, Aliyun) are unreachable from outside China over an unstable uplink. A direct Wi-Fi connection sidesteps both problems. + +List nearby networks: + +```bash +nmcli device wifi list +``` + +Connect with `--ask` so your password is prompted for (and kept out of shell history): + +```bash +sudo nmcli --ask device wifi connect "" +``` + +If you'd rather pick from a menu, `sudo nmtui` → **Activate a connection** works too. + +Verify the connection: + +```bash +nmcli device status +ip -4 addr show wlan0 +``` + +You should see an IP on `wlan0`. Now unplug the USB-Ethernet adapter — all further steps go over Wi-Fi. Reconnect from your laptop using the Wi-Fi IP: + +```bash +exit +ssh @ +``` + +:::caution Known caveat +The `unisoc_wifi` driver on this board can wedge silently — the link associates and DHCP succeeds, but no L3 traffic flows. If that happens, bouncing the NetworkManager connection (`sudo nmcli connection down "" && sudo nmcli connection up ""`) usually clears it. Try that before chasing AP/firewall issues. +::: + +--- + +## Step 12: Install avahi-daemon for `.local` hostname resolution + +So you can reach the board as `ambrosia-.local` from other devices: + +```bash +sudo apt update +sudo apt install -y avahi-daemon +``` + +Reboot to pick up the hostname + avahi changes together: + +```bash +sudo reboot +``` + +Wait ~30 seconds, then SSH back in at the new hostname: + +```bash +ssh @ambrosia-.local +``` + +--- + +## Step 13: Disable root SSH (optional but recommended) + +With your sudo user working and avahi up, lock down root SSH: + +```bash +sudo sed -i 's/^#*PermitRootLogin.*/PermitRootLogin no/' /etc/ssh/sshd_config +sudo systemctl restart ssh +``` + +--- + +## Step 14: Add swap and update + +### 14.1 Add swap space + +The OrangePi image already ships with ~490M of **zram** (RAM-compressed swap) enabled — you can check with `cat /proc/swaps`. That's helpful but for Ambrosia's JVM it's worth adding a real disk swapfile as a backstop: + +```bash +sudo fallocate -l 1G /swapfile +sudo chmod 600 /swapfile +sudo mkswap /swapfile +sudo swapon /swapfile +echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab +``` + +Verify with `free -h` — you should see ~1.5Gi of total swap (zram + disk). + +### 14.2 Update packages + +```bash +sudo apt upgrade -y +``` + +--- + +## Next Steps + +Your OrangePi is ready. Head over to [Install Ambrosia on Raspberry Pi](./rpi-install.md) — the install steps are written for the Pi Zero 2W but apply to the OrangePi too (same aarch64 install script, similar RAM/swap concerns). diff --git a/docs/quick-start-hardware/preinstalled.md b/docs/quick-start-hardware/preinstalled.md new file mode 100644 index 0000000..0190661 --- /dev/null +++ b/docs/quick-start-hardware/preinstalled.md @@ -0,0 +1,107 @@ +--- +title: "Take your Ambrosia unit home" +sidebar_position: 4 +slug: /quick-start-hardware/preinstalled +--- + +Your OrangePi was set up at the kermés, so it's configured to connect to the kermés Wi-Fi. To use it at home (or at another location), you need to tell it about your home Wi-Fi network. Pick **one** of the three methods below — whichever matches the hardware you have handy. **Method 1 is the easiest** — it only needs your phone. + +Your unit name is on the printed card that came with the OrangePi (e.g. `ambrosia-opi-3`). Replace `YOUR-UNIT` in the examples below with the actual name on your card. Your SSH password is also on the card. + +--- + +## Method 1: Phone + setup Wi-Fi (easiest, no extra hardware) + +**You'll need:** just your phone. + +When the OrangePi boots and can't find a Wi-Fi it knows, it broadcasts its own setup network. You join that network from your phone, pick your home Wi-Fi from a list, type the password, and you're done. + +1. Plug power into the OrangePi and wait about 60 seconds. +2. On your phone, open Wi-Fi settings and connect to **`YOUR-UNIT-setup`** (open network, no password). +3. Your phone should automatically open the setup page. If nothing pops up, open Chrome or Safari and go to `http://10.42.1.1`. +4. The page lists Wi-Fi networks the OrangePi can see. Tap your home Wi-Fi (or type the name if it's hidden), then enter the password — tap **Mostrar / Show** to verify what you typed. Tap **Conectar / Connect**. +5. On the next page, read the steps, then tap **Copy address and finish**. This: + - copies the POS address to your phone's clipboard, + - shuts down the setup network, + - and your phone reconnects to your home Wi-Fi. +6. Open Chrome or Safari, paste the address into the URL bar, and you're at the POS. + +The OrangePi now remembers your home Wi-Fi and will auto-connect from now on. + +:::tip +If the captive page doesn't open after you join `YOUR-UNIT-setup`, give it 5-10 seconds, then open `http://10.42.1.1` in a browser manually. +::: + +--- + +## Method 2: HDMI + USB keyboard (no other computer required) + +**You'll need:** a TV or monitor with HDMI, a mini-HDMI to HDMI cable, and a USB keyboard. + +1. Power off the OrangePi (unplug the USB-C cable). +2. Connect the OrangePi to your TV/monitor with the mini-HDMI cable, and plug in a USB keyboard. +3. Plug the power back in and wait about 60 seconds for the boot screen. +4. When you see `YOUR-UNIT login:` on the screen, type your unit name (from the card) and press Enter, then your password and Enter. +5. Connect to your home Wi-Fi by typing: + + ``` + sudo nmcli --ask device wifi connect "YOUR-HOME-WIFI-NAME" + ``` + + It will ask for your sudo password (the one on the card) and then your home Wi-Fi password. + +6. Confirm it worked: + + ``` + nmcli device status + ``` + + The `wlan0` line should say `connected` with your home Wi-Fi name on the right. + +7. Power off (`sudo poweroff`), unplug the HDMI cable and keyboard, and move the OrangePi to wherever you want to use it. Plug power back in — it'll auto-connect to your home Wi-Fi from now on. + +--- + +## Method 3: USB Ethernet cable (skip Wi-Fi entirely) + +**You'll need:** a USB-C to Ethernet adapter, an Ethernet cable, and your home router with a free LAN port. + +If you'd rather just plug the OrangePi into your router and skip Wi-Fi setup altogether, this is the fastest option. Once it's on the wired network, every device on your home Wi-Fi can reach it. + +1. Plug the USB-C Ethernet adapter into the OrangePi, then an Ethernet cable from the adapter to your router. +2. Plug in power and wait about 60 seconds. +3. From any device on your home network (phone, laptop), open `https://YOUR-UNIT.local/` in a browser. Click through the certificate warning (it's the unit's self-signed cert — same as at the kermés). You're at the POS. + +:::tip +If `YOUR-UNIT.local` doesn't resolve, find the OrangePi's IP in your router's "connected devices" admin page and use `https://192.168.x.y/` instead. +::: + +You can leave the unit on Ethernet permanently. If you'd later prefer Wi-Fi, unplug the Ethernet cable and the unit will boot into Method 1's setup AP next time you power-cycle it. + +--- + +## Finding your Wi-Fi name and password + +If you don't know your home Wi-Fi name (SSID) or password, here are the common places to look: + +1. **Sticker on the router.** Most home routers have the default network name and password printed on a sticker on the bottom or back. Look for labels like "WiFi Name", "SSID", or "Network Name", and "Password", "WPA Key", or "Wi-Fi Password". +2. **A phone that's already connected.** + - **Android (10+):** Settings → Network & Internet → Internet → tap your Wi-Fi → Share → scan the QR or reveal the password. + - **iOS (16+):** Settings → Wi-Fi → tap the (i) next to your network → tap Password to reveal. +3. **Your ISP's app or account portal.** Providers like Totalplay, Telmex, Izzi, and Megacable let you view (and change) your Wi-Fi credentials in their mobile app or online account. +4. **Router admin page.** From a device already on your Wi-Fi, open `http://192.168.1.1` or `http://192.168.100.1` in a browser. Log in with admin credentials (often also on the router sticker) and look under Wireless / Wi-Fi settings. + +Still stuck? Ask in the Telegram support chat — we can walk you through it. + +--- + +## Troubleshooting + +- **`YOUR-UNIT-setup` doesn't appear in your phone's Wi-Fi list.** Wait a full 60 seconds after powering on, then re-scan. If still nothing, the unit may have auto-connected to a known network — power-cycle it somewhere out of range of any Wi-Fi it knows. +- **Setup page doesn't pop up after joining `YOUR-UNIT-setup`.** Open Chrome/Safari and go to `http://10.42.1.1` manually. +- **Wrong Wi-Fi password typed.** The setup AP comes back up after a failed attempt — just rejoin `YOUR-UNIT-setup` and try again. (If you used Method 2 or 3: `sudo nmcli connection delete "YOUR-HOME-WIFI-NAME"` then repeat the connect command.) +- **Still on the kermés Wi-Fi when you don't want to be.** At home, the kermés Wi-Fi isn't in range so it won't auto-connect — just add your home one and the unit will prefer whichever is available. +- **Forgot your password / locked yourself out.** Reach out in the Telegram support chat (QR on your card). We can help reset it via a Wi-Fi-free method. +- **Nothing resolves and nothing works.** Power off, bring the unit to the kermés organizer or ping support on Telegram; we can reimage it for you. + +After you're connected, access the POS UI at `https://YOUR-UNIT.local/` from any device on your home Wi-Fi — same as at the kermés, same cert warning to click through. diff --git a/docs/quick-start-hardware/rpi-install.md b/docs/quick-start-hardware/rpi-install.md new file mode 100644 index 0000000..31933ba --- /dev/null +++ b/docs/quick-start-hardware/rpi-install.md @@ -0,0 +1,197 @@ +--- +title: "Install Ambrosia on Raspberry Pi" +sidebar_position: 2 +slug: /quick-start-hardware/rpi-install +--- + +This guide assumes you have a Raspberry Pi Zero 2W set up and accessible via SSH. If not, see [Raspberry Pi setup](./rpi-setup.md) first. + +The notes here are tuned for the Pi Zero 2W (512MB RAM). For Ambrosia install on a regular Linux machine, see [Quick Start - Native](/quick-installation-native). + +--- + +## Option A: Native Install (recommended for Pi Zero 2W) + +The Pi Zero 2W only has 512MB of RAM, so running natively (without Docker overhead) is the better option. + +### A1: Install dependencies + +You'll need JDK 21 (for the server), Node.js 22 (for the client), and a few system packages. + +#### System packages (~2 min) + +```bash +sudo apt update +sudo apt install -y curl unzip zip tar gpg +``` + +#### Install JDK 21 with SDKMAN (~5 min) + +```bash +curl -s "https://get.sdkman.io" | bash +source "$HOME/.sdkman/bin/sdkman-init.sh" +sdk install java 21.0.8-tem +``` + +Verify: + +```bash +java -version +``` + +#### Install Node.js 22 with nvm (~3 min) + +```bash +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash +source "$HOME/.nvm/nvm.sh" +nvm install 22 +``` + +Verify: + +```bash +node -v +npm -v +``` + +### A2: Run the Ambrosia installer (~8 min) + +The install script downloads and sets up all three components (phoenixd, ambrosia server, ambrosia client). On a Pi Zero 2W it takes about 8 minutes end-to-end — most of that is `npm install` for the client: + +```bash +curl -fsSL https://raw.githubusercontent.com/olympus-btc/ambrosia/refs/heads/main/scripts/install.sh | bash -s -- --yes +``` + +This will: +- Download and verify **phoenixd** (Lightning node) for ARM64 +- Download the **Ambrosia server** JAR +- Download and install the **Ambrosia client** (Next.js) +- Set up systemd services for all three components + +### A3: Verify everything is running + +```bash +sudo systemctl status phoenixd +sudo systemctl status ambrosia +sudo systemctl status ambrosia-client +``` + +All three should show `active (running)`. + +### A4: Access Ambrosia + +Open a web browser on any device on the same network and go to: + +``` +http://ambrosia-.local:3000 +``` + +You should see the Ambrosia POS interface. + +--- + +## Upgrading an existing install + +To upgrade to a newer Ambrosia release, stop the services first (the installer overwrites files but does not stop them), then re-run the installer. The installer re-enables and starts all three services when it finishes. Expect ~8 minutes on a Pi Zero 2W. + +```bash +sudo systemctl stop ambrosia-client ambrosia phoenixd +curl -fsSL https://raw.githubusercontent.com/olympus-btc/ambrosia/refs/heads/main/scripts/install.sh | bash -s -- --yes +sudo systemctl status phoenixd ambrosia ambrosia-client --no-pager +``` + +--- + +## Option B: Docker Install + +If you prefer Docker (or are running on a Pi with more RAM): + +### B1: Install Docker + +```bash +curl -fsSL https://get.docker.com | sudo sh +sudo usermod -aG docker $USER +``` + +Log out and back in: + +```bash +exit +``` + +SSH back in, then verify: + +```bash +docker --version +docker compose version +``` + +### B2: Get the Docker Compose file + +```bash +mkdir ~/ambrosia && cd ~/ambrosia +curl -fsSL https://raw.githubusercontent.com/olympus-btc/ambrosia/main/docker-compose.yml -o docker-compose.yml +``` + +### B3: Start Ambrosia + +```bash +docker compose up -d --wait +docker compose restart +``` + +### B4: Check that everything is running + +```bash +docker compose ps +``` + +All three services should be running. + +### B5: Access Ambrosia + +``` +http://ambrosia-.local:3000 +``` + +--- + +## Troubleshooting + +### Out of memory (both methods) + +The Pi Zero 2W has only 512MB of RAM. If things are getting killed, add swap (or increase the swap from [Raspberry Pi setup, Step 5.1](./rpi-setup.md)): + +```bash +sudo dphys-swapfile swapoff +sudo sed -i 's/CONF_SWAPSIZE=.*/CONF_SWAPSIZE=1024/' /etc/dphys-swapfile +sudo dphys-swapfile setup +sudo dphys-swapfile swapon +``` + +### Services won't start (native) + +Check logs: + +```bash +sudo journalctl -u phoenixd -n 50 +sudo journalctl -u ambrosia -n 50 +sudo journalctl -u ambrosia-client -n 50 +``` + +### Containers won't start (Docker) + +```bash +docker compose logs +free -h +``` + +### JVM is very slow to start + +Normal on the Pi Zero 2W. The first startup can take a few minutes. Subsequent starts are faster. + +### Can't access the web interface + +- Verify services are running (systemctl status or docker compose ps) +- Try using the IP address instead of `.local` +- Check that port 3000 isn't blocked by a firewall: `sudo ufw status` diff --git a/docs/quick-start-hardware/rpi-setup.md b/docs/quick-start-hardware/rpi-setup.md new file mode 100644 index 0000000..a9597df --- /dev/null +++ b/docs/quick-start-hardware/rpi-setup.md @@ -0,0 +1,168 @@ +--- +title: "Raspberry Pi Zero 2W setup" +sidebar_position: 1 +slug: /quick-start-hardware/rpi-setup +--- + +Setting up a Raspberry Pi Zero 2W from scratch, ready to run Ambrosia. + +![Unopened RPi kit](./img/rpi-kit-unopened.jpg) + +## What You'll Need + +**[Vilros Raspberry Pi Zero 2W Starter Kit](https://www.amazon.com.mx/Vilros-Raspberry-Zero-multiprop%C3%B3sito-HDMI-adaptadores/dp/B09M1PS35R)** — includes: +- Raspberry Pi Zero 2W board +- Multi-purpose ABS case +- Micro-USB power supply +- Mini-HDMI to HDMI adapter +- Micro-USB to USB-A adapter + +**Sold separately:** +- microSD card — 32GB or larger (a SanDisk Ultra 32GB works well; not included in the Vilros bundle) +- A computer with a microSD card reader (to flash the OS) + +![Opened Vilros kit with microSD added](./img/vilros-kit-opened.jpg) + +**Software (on your computer):** +- [Raspberry Pi Imager](https://www.raspberrypi.com/software/) (free, works on Windows/Mac/Linux) + +**Network:** +- Wi-Fi network (the Pi Zero 2W has built-in Wi-Fi) + +--- + +## Step 1: Flash Raspberry Pi OS onto the SD Card + +We'll use **Raspberry Pi Imager** to write the operating system to the microSD card. This tool handles downloading the OS image and writing it for you. + +### 1.1 Install Raspberry Pi Imager + +Download and install from [raspberrypi.com/software](https://www.raspberrypi.com/software/). + +On Debian/Ubuntu, you can also install the `.deb` directly: + +```bash +wget https://github.com/raspberrypi/rpi-imager/releases/download/v2.0.8/rpi-imager_2.0.8_amd64.deb +sudo apt install ./rpi-imager_2.0.8_amd64.deb +``` + +### 1.2 Open the SD card packaging and insert it into your computer + +Insert the 32GB microSD card into your computer's card reader (you may need a microSD-to-SD adapter or a USB card reader). + +### 1.3 Open Raspberry Pi Imager and configure it + +```bash +rpi-imager +``` + +1. Click **CHOOSE DEVICE** and select **Raspberry Pi Zero 2 W** +2. Click **CHOOSE OS** and select **Raspberry Pi OS (other)** → **Raspberry Pi OS Lite (64-bit)** + - We use **Raspberry Pi OS Lite** because it has the smallest memory footprint — important on the Zero 2W's 512MB RAM + - **Lite** = no desktop (we'll run everything headless, no monitor needed) + - **64-bit** is required because Ambrosia's dependencies need ARM64 + - Ubuntu Server also works (it's Debian-based too), but uses more RAM at idle +3. Click **CHOOSE STORAGE** and select your 32GB microSD card + +### 1.4 Configure settings (important!) + +Before writing, click the **gear icon** (⚙) or **NEXT** and then **EDIT SETTINGS** to customize: + +**General tab:** +- **Set hostname:** `ambrosia-` — replace `` with your name (e.g. `ambrosia-chris`). Everyone on the same network needs a unique hostname! +- **Set username and password:** Pick a username and a strong password — you'll use these to log in via SSH +- **Configure wireless LAN:** Enter your Wi-Fi network name (SSID) and password +- **Set locale settings:** Choose your time zone and keyboard layout + +**Services tab:** +- **Enable SSH:** Check this box and select **Use password authentication** + +These settings are critical — without them you won't be able to connect to the Pi remotely. + +### 1.5 Write the image + +1. Click **SAVE**, then **YES** to apply the custom settings +2. Click **YES** to confirm writing (this will erase everything on the SD card) +3. Wait for the write and verification to complete + +--- + +## Step 2: Boot the Raspberry Pi + +1. Remove the microSD card from your computer +2. Insert it into the Raspberry Pi Zero 2W (the slot is on the bottom of the board) +3. Connect the micro-USB power supply + +The Pi will boot up and automatically connect to your Wi-Fi network. Give it a minute or two for the first boot — it needs to resize the filesystem and apply your settings. + +--- + +## Step 3: Connect to the Pi via SSH + +From your computer, open a terminal and connect: + +```bash +ssh @ambrosia-.local +``` + +(Replace `` with the username you set in Step 1.4, and `` with the name you chose for your hostname) + +If `ambrosia-.local` doesn't resolve, you may need to find the Pi's IP address from your router's admin page, and connect with: + +```bash +ssh @ +``` + +Accept the host key fingerprint when prompted, then enter your password. + +You should now be logged into your Raspberry Pi. + +--- + +## Step 4: Wait for automatic updates to finish + +On first boot, Raspberry Pi OS runs `unattended-upgrades` in the background. This holds the apt lock and can take 10-20 minutes on the Pi Zero 2W. You **must** wait for it to finish before installing anything. + +You can check if it's still running: + +```bash +sudo tail -f /var/log/unattended-upgrades/unattended-upgrades.log +``` + +Wait until you see it finish, then Ctrl+C. + +## Step 5: Update the system and add swap + +### 5.1 Add swap space + +The Pi Zero 2W only has 512MB of RAM, which isn't enough to comfortably run Ambrosia. Add 1GB of swap: + +```bash +sudo fallocate -l 1G /swapfile +sudo chmod 600 /swapfile +sudo mkswap /swapfile +sudo swapon /swapfile +echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab +``` + +Verify with `free -h` — you should see 1.0Gi of swap. + +### 5.2 Update packages + +```bash +sudo apt update && sudo apt upgrade -y +``` + +### 5.3 Disable unattended-upgrades (optional) + +To save RAM on this constrained device: + +```bash +sudo apt remove -y unattended-upgrades +``` + +--- + +## Next Steps + +Your Pi is ready. Head over to [Install Ambrosia on Raspberry Pi](./rpi-install.md) to set up the POS system. diff --git a/docusaurus.config.js b/docusaurus.config.js index f427cd0..f2a7ea5 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -105,6 +105,10 @@ const config = { label: 'Quick Start - Native', to: '/quick-start-native', }, + { + label: 'Quick Start - Hardware', + to: '/quick-start-hardware', + }, ], } ], diff --git a/i18n/es/docusaurus-plugin-content-docs/current/quick-start-hardware/index.md b/i18n/es/docusaurus-plugin-content-docs/current/quick-start-hardware/index.md new file mode 100644 index 0000000..f7db08d --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/quick-start-hardware/index.md @@ -0,0 +1,16 @@ +--- +sidebar_position: 5 +title: Quick Start - Hardware +--- + +Guía paso a paso para correr Ambrosia en una computadora de una sola placa (SBC). Tres audiencias comparten esta sección: + +1. **DIY — Raspberry Pi Zero 2W** — tienes las piezas y quieres armar una RPi desde cero. + - [Raspberry Pi setup](/quick-start-hardware/rpi-setup) — flashear, arrancar, SSH + - [Install Ambrosia on Raspberry Pi](/quick-start-hardware/rpi-install) — nativo o Docker +2. **DIY — OrangePi Zero 2W** — tienes las piezas y quieres armar una OPi desde cero. + - [OrangePi setup](/quick-start-hardware/opi-setup) — flashear, arrancar, SSH (luego [Install Ambrosia](/quick-start-hardware/rpi-install)) +3. **Preinstalada** — recibiste una unidad ya configurada y solo quieres usarla. + - [Llévate tu unidad Ambrosia a casa](/quick-start-hardware/preinstalled) — configuración Wi-Fi de primer arranque (inglés + español) + +Los flujos DIY hoy son manuales. La meta a largo plazo es un solo comando que produzca una imagen reproducible verificable que flasheas a una microSD — ver el árbol [`hardware/`](https://github.com/olympus-btc/ambrosia/tree/main/hardware) en el repo principal para el estado. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/quick-start-hardware/preinstalled.md b/i18n/es/docusaurus-plugin-content-docs/current/quick-start-hardware/preinstalled.md new file mode 100644 index 0000000..a3f0479 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/quick-start-hardware/preinstalled.md @@ -0,0 +1,107 @@ +--- +title: "Llévate tu unidad Ambrosia a casa" +sidebar_position: 4 +slug: /quick-start-hardware/preinstalled +--- + +Tu OrangePi se configuró en la kermés, así que está conectada al Wi-Fi de la kermés. Para usarla en casa (u otro lugar) necesitas decirle el nombre y contraseña de tu Wi-Fi. Elige **uno** de los tres métodos según el equipo que tengas a la mano. **El Método 1 es el más fácil** — solo necesitas tu teléfono. + +El nombre de tu unidad está en la tarjeta impresa que recibiste (por ejemplo `ambrosia-opi-3`). Sustituye `TU-UNIDAD` en los ejemplos por el nombre que aparezca en tu tarjeta. Tu contraseña SSH también está en la tarjeta. + +--- + +## Método 1: Teléfono + Wi-Fi de configuración (más fácil, sin equipo extra) + +**Necesitas:** solo tu teléfono. + +Cuando la OrangePi enciende y no encuentra una red Wi-Fi conocida, levanta su propia red de configuración. Te conectas a esa red desde el teléfono, eliges tu Wi-Fi de la lista, escribes la contraseña y listo. + +1. Conecta la corriente a la OrangePi y espera unos 60 segundos. +2. En tu teléfono, abre los ajustes de Wi-Fi y conéctate a **`TU-UNIDAD-setup`** (red abierta, sin contraseña). +3. El teléfono debería abrir la página de configuración automáticamente. Si no aparece, abre Chrome o Safari y entra a `http://10.42.1.1`. +4. La página muestra las redes Wi-Fi que la OrangePi puede ver. Toca tu Wi-Fi de casa (o escribe el nombre si está oculta), luego escribe la contraseña — toca **Mostrar** para verificar lo que escribiste. Toca **Conectar**. +5. En la siguiente pantalla, lee los pasos y luego toca **Copiar dirección y terminar**. Esto: + - copia la dirección del POS al portapapeles del teléfono, + - apaga la red de configuración, + - y tu teléfono se reconecta solo a tu Wi-Fi de casa. +6. Abre Chrome o Safari, pega la dirección en la barra y entrarás al POS. + +La OrangePi ya recuerda tu Wi-Fi de casa y se conectará sola de ahora en adelante. + +:::tip +Si la página de configuración no aparece sola al unirte a `TU-UNIDAD-setup`, espera 5-10 segundos y abre `http://10.42.1.1` manualmente en el navegador. +::: + +--- + +## Método 2: HDMI + teclado USB (no requiere otra computadora) + +**Necesitas:** una TV o monitor con HDMI, un cable mini-HDMI a HDMI y un teclado USB. + +1. Apaga la OrangePi (desconecta el cable USB-C). +2. Conéctala a tu TV/monitor con el cable mini-HDMI y conecta un teclado USB. +3. Vuelve a conectar la corriente y espera unos 60 segundos hasta que aparezca la pantalla de inicio. +4. Cuando aparezca `TU-UNIDAD login:` en la pantalla, escribe el nombre de tu unidad (de la tarjeta) y presiona Enter, luego tu contraseña y Enter. +5. Conéctate a tu Wi-Fi de casa con: + + ``` + sudo nmcli --ask device wifi connect "NOMBRE-DE-TU-WIFI" + ``` + + Te pedirá tu contraseña de sudo (la misma de la tarjeta) y luego la contraseña de tu Wi-Fi de casa. + +6. Verifica que funcionó: + + ``` + nmcli device status + ``` + + La línea de `wlan0` debe decir `connected` con el nombre de tu Wi-Fi a la derecha. + +7. Apaga con `sudo poweroff`, desconecta el HDMI y el teclado, mueve la OrangePi al lugar donde la vayas a usar. Al conectar la corriente se conectará sola a tu Wi-Fi de casa. + +--- + +## Método 3: Cable Ethernet USB (sin Wi-Fi) + +**Necesitas:** un adaptador USB-C a Ethernet, un cable Ethernet y tu router con un puerto LAN libre. + +Si prefieres simplemente conectar la OrangePi al router y olvidarte del Wi-Fi, este es el camino más rápido. Una vez en la red cableada, cualquier dispositivo en tu Wi-Fi de casa puede acceder a ella. + +1. Conecta el adaptador USB-C a Ethernet a la OrangePi, y un cable Ethernet del adaptador al router. +2. Conecta la corriente y espera unos 60 segundos. +3. Desde cualquier dispositivo en tu red de casa (teléfono, laptop), abre `https://TU-UNIDAD.local/` en el navegador. Acepta la advertencia del certificado (es el certificado autofirmado de la unidad — igual que en la kermés). Listo, ya estás en el POS. + +:::tip +Si `TU-UNIDAD.local` no resuelve, busca la IP de la OrangePi en la página de "dispositivos conectados" de tu router y usa `https://192.168.x.y/`. +::: + +Puedes dejar la unidad en Ethernet de forma permanente. Si después prefieres Wi-Fi, desconecta el cable Ethernet y la unidad arrancará con el AP de configuración del Método 1 al volver a encenderla. + +--- + +## Cómo encontrar el nombre y contraseña de tu Wi-Fi + +Si no sabes el nombre (SSID) o contraseña de tu Wi-Fi de casa, estos son los lugares más comunes donde encontrarlos: + +1. **Calcomanía del router.** La mayoría de los routers traen el nombre de la red y la contraseña de fábrica impresos en una calcomanía en la parte de abajo o atrás. Busca etiquetas como "WiFi Name", "SSID" o "Nombre de red", y "Password", "WPA Key" o "Contraseña". +2. **Un teléfono que ya está conectado a esa red.** + - **Android (10+):** Ajustes → Red e internet → Internet → toca tu Wi-Fi → Compartir → muestra el código QR o revela la contraseña. + - **iOS (16+):** Ajustes → Wi-Fi → toca la (i) junto a tu red → toca Contraseña para verla. +3. **App o portal de tu proveedor de internet.** Totalplay, Telmex, Izzi y Megacable te permiten ver (y cambiar) las credenciales del Wi-Fi desde su app o portal en línea. +4. **Página de administración del router.** Desde un dispositivo ya conectado a tu Wi-Fi, abre `http://192.168.1.1` o `http://192.168.100.1` en un navegador. Inicia sesión con las credenciales de admin (a veces también están en la calcomanía) y busca la sección de Wireless o Wi-Fi. + +¿Sigues atorado? Pregunta en el chat de soporte de Telegram — te ayudamos a encontrarlos. + +--- + +## Solución de problemas + +- **`TU-UNIDAD-setup` no aparece en el listado de Wi-Fi del teléfono.** Espera 60 segundos completos después de encender la unidad y vuelve a buscar. Si aún no aparece, puede que se haya conectado a una red conocida — apágala y enciéndela en un lugar fuera del alcance de cualquier Wi-Fi que conozca. +- **La página de configuración no aparece al unirte a `TU-UNIDAD-setup`.** Abre Chrome o Safari y entra a `http://10.42.1.1` manualmente. +- **Escribiste mal la contraseña del Wi-Fi.** El AP de configuración vuelve a aparecer si falla el intento — solo vuelve a unirte a `TU-UNIDAD-setup` y prueba otra vez. (Si usaste el Método 2 o 3: `sudo nmcli connection delete "NOMBRE-DE-TU-WIFI"` y luego repite el comando connect.) +- **Sigue conectado al Wi-Fi de la kermés cuando no quieres.** En casa el Wi-Fi de la kermés no está al alcance, así que no se conectará solo — basta con agregar tu Wi-Fi de casa y la unidad usará la que esté disponible. +- **Olvidaste la contraseña o te bloqueaste.** Escríbenos al chat de soporte de Telegram (QR en tu tarjeta). Te ayudamos con un reset sin Wi-Fi. +- **Nada resuelve ni funciona.** Apaga la unidad, tráela al organizador de la kermés o pide ayuda en Telegram — podemos reimaginar la tarjeta por ti. + +Cuando estés conectado, abre la app del POS en `https://TU-UNIDAD.local/` desde cualquier dispositivo en tu Wi-Fi de casa — igual que en la kermés, con la misma advertencia del navegador que hay que aceptar.