# UNO Q — Setup, Operating System & App Lab

## The operating systems, restated

- **MPU:** full **Debian Linux** with a desktop. It has a package manager (`apt`), systemd services, users/permissions, a filesystem, networking — treat it like any Debian machine. Arduino **App Lab** is pre-installed.
- **MCU:** **Zephyr OS** running your Arduino sketch. You rarely interact with Zephyr directly; you write ordinary Arduino code and App Lab / the IDE handles the rest.

## Two development environments

### Arduino App Lab (primary)
- **Pre-installed on the board.** Also installable on your PC (Windows/macOS/Linux) from the Arduino software page for Network-Mode development.
- An **App** = a Python program (runs on Linux/MPU) **+** an Arduino sketch (runs on MCU) **+ Bricks**.
- **Bricks** are reusable, pre-packaged building blocks (e.g. vision, audio, I/O helpers) you compose into an App — this is how App Lab gets you to AI/vision features quickly without writing everything from scratch.
- Runs two ways:
  - **Single-Board-Computer (SBC) mode** — App Lab runs *on the board* with a monitor/keyboard/mouse attached via the dongle.
  - **Network Mode** — App Lab runs on your PC and talks to the board over the LAN (see remote-access reference).

### Arduino IDE (beta) — MCU only
- Programs **only the STM32 microcontroller**. It **cannot** program the Qualcomm processor. For anything touching Linux/Python, use App Lab.
- Install the core: **Tools → Board → Boards Manager → search "UNO Q" → install "Arduino UNO Q Zephyr Core."**
- If it doesn't appear, add this to **File → Preferences → Additional Boards Manager URLs**:
  ```
  https://downloads.arduino.cc/packages/package_zephyr_index.json
  ```
- Then select **Tools → Board → Arduino UNO Q Board**, pick the **Port**, and upload as usual. The classic `File → Examples → 01.Basics → Blink` works (`LED_BUILTIN` = the red channel of the built-in RGB LED).

## First boot as a Single-Board Computer

1. Plug the USB-C dongle into the board's USB-C port.
2. Keyboard + mouse into the dongle's USB-A ports; monitor into the dongle's HDMI; power supply (**+5 VDC / 3 A min**) into the dongle.
3. It boots automatically. At the Debian login the default user is **`arduino`**; you set a password.
4. App Lab's first-run wizard walks through keyboard layout, **board name**, **Wi-Fi**, and login credentials. The board name becomes the mDNS hostname (`<name>.local`) used for Network Mode and SSH.

The preloaded desktop includes Chromium, a file manager, a terminal, Vim, and media playback. Install more software the normal Debian way, e.g. `sudo apt install vlc`.

## Linux host setup (REQUIRED when driving the board from a Linux PC)

On a Linux PC, App Lab talks to the board over USB and needs udev permissions, or **it fails silently** and flashing throws permission errors. The board presents two USB identities:

- **Operating mode:** VID `2341`, PID `0078`
- **Emergency Download (EDL) mode:** VID `05c6`, PID `9008`

### Install the udev rules (canonical one-liner)
```bash
echo \
'# Operating mode
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2341", ATTRS{idProduct}=="0078", MODE="0660", TAG+="uaccess"
# EDL mode
SUBSYSTEMS=="usb", ATTRS{idVendor}=="05c6", ATTRS{idProduct}=="9008", MODE="0660", TAG+="uaccess"' \
| sudo tee "/etc/udev/rules.d/60-Arduino-UNO-Q.rules" \
&& sudo udevadm control --reload-rules \
&& sudo udevadm trigger
```
`MODE="0660"` sets the device-file permissions; `TAG+="uaccess"` grants the logged-in user access via systemd-logind.

### Verify
```bash
cat /etc/udev/rules.d/60-Arduino-UNO-Q.rules
lsusb | grep -E "2341:0078|05c6:9008"
adb devices          # board should be listed
adb shell            # drops you into a shell on the board
```

### Apply
**Disconnect and reconnect the board** (wait a few seconds), then restart App Lab so it re-reads permissions.

### Alternative: official post-install script
From the ArduinoCore-zephyr repo — creates `/etc/udev/rules.d/60-arduino-zephyr.rules`:
```bash
cd ~/Downloads
wget https://raw.githubusercontent.com/arduino/ArduinoCore-zephyr/main/post_install.sh
chmod +x post_install.sh
sudo ./post_install.sh
```
(or `curl -O <same URL>`, or `git clone https://github.com/arduino/ArduinoCore-zephyr.git` then run `post_install.sh`). Reconnect the board afterward.

## Hello World (Blink) to confirm the toolchain
In App Lab the Examples section opens on launch → open **Blink LED** → **Run**. Success = the **red** channel of the built-in RGB LED blinks 1 s on / 1 s off. That LED is driven by the STM32 via the sketch, so a successful blink proves the MCU side is programmable.

## Running an App at startup (kiosk / standalone projects)
- You **cannot** set a built-in *Example* as the startup app directly — first **copy it to a new App** or create your own.
- In the App: click the **▼** arrow next to the **Run** button (top-right) → toggle **Run at startup** ON. A **DEFAULT** badge confirms it.
- CLI equivalent:
  ```bash
  arduino-app-cli properties set default user:<NAME_OF_YOUR_APP>
  ```

## The App Lab CLI (`arduino-app-cli`)
Runs on the board (use it over SSH for headless control):
```bash
arduino-app-cli app start ~/ArduinoApps/<project-name>   # start an app
arduino-app-cli app logs  ~/ArduinoApps/<project-name>   # stream its logs
arduino-app-cli app stop  ~/ArduinoApps/<project-name>   # stop it
arduino-app-cli properties set default user:<app-name>   # set autostart app
```
Apps live under `~/ArduinoApps/` on the board.