PeaPodOS

Main software for PeaPod. Scripts are written for MacOS, and probably work on other Unix-like systems.

Table of Contents

• Design
  • Architecture
    • environment
    • index
    • server
• Usage
  • Development
    • Native Simulator Development
    • Packing for NPM
    • Exporting Software Bundle
    • QEMU Raspberry Pi Simulator
  • Production
    • Build Raspberry Pi Image
    • Raspberry Pi 400 First-Time Setup
  • Installation
  • Execution

Design

A two-part system, consisting of a high-level software application and a low-level microcontroller firmware, designed for remote monitoring and configuration of control systems.

The software is written in TypeScript and runs on any compatible computer system with an internet connection, persistent storage, and a UART serial interface (i.e. Raspberry Pi).

The firmware is written in Arduino C++ and runs on any compatible microcontroller system with UART serial and I2C interfaces (i.e. Adafruit ESP32 Feather V2). See ./microcontroller/README.md for more information.

Ensure UART voltage levels are compatible (i.e. 3.3V for both Raspberry Pi and Adafruit ESP32 Feather V2).

Architecture

environment

Priority:

1. User input
2. Command-line arguments
3. Environment variables
4. Defaults

index

run tests, flash firmware, launch server

server

start menu

• publishing mode selection (Local Filesytem, Firebase, Dashboard)
• Firebase Device Flow Authentication
  • Provider Selection (Google, GitHub)
  • Device Code & URL
• Microcontroller Serial Port Selection
• Dashboard Webserver Hostname & Port Selection

serial communication

• bidirectional
• JSON-formatted
• newline-delimited
• encoding: device commands, system configuration
• decoding: telemetry/debugging

WebSockets API w/ Callbacks

• camera capture and image streaming
• serial passthrough
• intervals
• linker
• firmware flashing
• scheduler

Control Systems (TODO)

dashboard webserver

• Debugging Console
• Telemetry Charts
• Calendar + DataGrid
• Interval & Event Scheduler
  • Microcontroller Instructions
  • Tasks

Usage

Development

There are three entrypoints:

1. Docker compose development environment for native simulator development
2. NPM package for development and publishing
3. Exported software bundle for development deployment

Native Simulator Development

1. git clone https://github.com/PeaPodTechnologies/PeaPod.git
2. cd software
3. chmod +x ./scripts/attach.sh
4. docker compose up
5. In a separate terminal, ./scripts/attach.sh to attach to the container and run the software.

Packing for NPM

1. git clone https://github.com/PeaPodTechnologies/PeaPod.git
2. cd software
3. chmod +x ./scripts/pack.sh
4. ./scripts/pack.sh to build the software and create a .tgz package in ./dist/peapodos.tgz for publishing to NPM.

Exporting Software Bundle

1. Execute scripts/export.sh WITH NO ARGUMENTS to compile TypeScript to JavaScript and bundle the webserver, creating an ./out.tar.gz archive containing the compiled software.
2. Optional: Execute scripts/upload.sh <hostname> to upload the ./out.tar.gz archive to the Raspberry Pi home directory, where <hostname> is the hostname of the Raspberry Pi (e.g. peapod.local).
3. Unzip the ~/out.tar.gz archive with tar -xzf ~/out.tar.gz -C ~.

QEMU Raspberry Pi Simulator

1. Install dependencies: brew install qemu
2. Build the Raspberry Pi OS Lite (64-bit) QEMU-compatible image: ./qemu-image.sh
3. Build the Docker image for the QEMU simulator: ./qemu-build.sh
4. Run the QEMU simulator container with ./qemu-run.sh deploy/<date>-peapod-lite-qemu.img to install boot the Raspberry Pi OS Lite (64-bit) image in a virtual machine.

Production

This targets Raspberry Pi 400 with USB serial and power connection to an Adafruit ESP32 Feather V2 microcontroller.

Build Raspberry Pi Image

The following are performed on a computer with an internet connection, Docker, and Homebrew installed:

1. Format a microSD card (>=32GB) with a single FAT partition.
2. Download the Raspberry Pi Imager (Download).
3. Build the Raspberry Pi OS (64-bit) image: build.sh. This creates a Docker build container that produces a .zip file at deploy/*.zip. This requires Homebrew and installs gnu-sed.
4. Flash the SD card with the Raspberry Pi OS (64-bit) image using Raspberry Pi Imager, and select deploy/*.zip as the custom image.

Note: A custom PeaPodOS image will be released in the future.

Raspberry Pi 400 First-Time Setup

1. Plug in a keyboard, display, and mouse, insert the included microSD card (if not already inserted), and power on the Raspberry Pi 400.

The following are performed on the Raspberry Pi 400, with a keyboard, mouse, and monitor:

2. Login. If using the graphical desktop, open a terminal.
3. Execute sudo raspi-config and perform these steps to setup the Pi:
   1. System Options > Wireless Lan - Setup WiFi and connect to the Internet (if not set from within imager)
   2. System Options > Hostname - Set a unique hostname, e.g. peapod (if not set from within imager)
   3. System Options > Boot/Auto Login - Select Console Autologin (B2)
   4. Interface Options > SSH - Enable SSH Server (if not set from within imager)
   5. Interface Options > Serial Port - Disable serial login shell, but Enable the serial port hardware
   6. Localisation Options > Locale (i.e. en_US.UTF-8)
   7. Localisation Options > Timezone (i.e. US > Eastern)
   8. Localisation Options > Keyboard (i.e. Generic 105-key > English (US) > Default > No compose key)
   9. Optional: Advanced Options > Expand Filesystem
   10. Reboot to save: sudo reboot -f

You can now SSH into the Raspberry Pi to perform the rest of the setup, or continue with the keyboard and monitor.

Installation

1. Update package listings, upgrade existing packages: sudo apt update && sudo apt full-upgrade -y

2. Install Node.JS, the Node package manager, and Python dependencies: sudo apt install -y nodejs npm python3-venv python3-dev

3. Install main software package: sudo npm i -g @peapodtech/peapodos --save

4. Install PlatformIO Core

5. Populate a ~/.env file based on ./.env.template with serial port and webserver configuration, and, if using Firebase, Firebase configuration and Google and/or GitHub auth configuration.

6. Connect a USB cable from the computer (i.e. Raspberry Pi 400) to the microcontroller (i.e. Adafruit ESP32 Feather V2), and verify that the serial port is available and openable by executing peapodos and following the prompt to select "Test Serial". The serial port should be something like /dev/ttyACM0 (NOT /dev/ttyS0, this is the GPIO UART). Press Ctrl-C to exit the test when finished.

7. Perform first-time microcontroller firmware flashing by executing peapodos and following the prompt to select "Flash Firmware". The serial port should be something like /dev/ttyACM0 (NOT /dev/ttyS0, this is the GPIO UART).

Execution

1. Run the main program by executing peapodos and following the prompt to select "Launch Server". You may exit at any time by pressing Ctrl-C.

2. Follow the prompts to select publishing modes (Local Filesystem, Firebase, and/or Dashboard), and if applicable, perform Firebase Device Flow Authentication.

3. Select the appropriate serial port (i.e. /dev/ttyS0 for GPIO UART-Arduino Serial1, /dev/ttyACM0 for USB-Arduino Serial) to connect to the microcontroller.

4. If dashboard publishing was selected, enter a hostname and port when prompted (default is 0.0.0.0:3000); the webserver should start, making the dashboard accessible at the displayed hostname and port.

5. The console will begin printing raw telemetry and debugging information from the microcontroller.