Skip to content

Latest commit

 

History

History
130 lines (99 loc) · 7.38 KB

DEVELOPING.md

File metadata and controls

130 lines (99 loc) · 7.38 KB

Developing for the AmpliPi Project

Thanks for considering developing for AmpliPi. We appreciate your support!

Developing the webapp

To develop for the webapp, you will need to install nodejs and any dependencies for ReactJS

Developing on a separate computer

This allows remote development with the ability to test changes on your AmpliPi

  1. Checkout this repo using git on a linux based system. You will need git-lfs installed as well to handle large files. A git bash shell on windows works fine as well, we suggest Windows Subsystem for Linux (WSL).
  2. Make changes with your favorite editor, we suggest vscode
  3. Use scripts/deploy to deploy the latest software. The pi must have access to the internet to successfully run this script.

Installing Node.js

scripts/deploy attempts to install any dependencies automatically, except for Node.js. AmpliPi is currently built with Node.js version 18.

TODO: Can Ubuntu 22.04 or Debian Bookworm use what's in their default apt repos?

For Ubuntu <=20.04, the version of Node.js from apt is outdated. We use Node Version Manager to install a newer version. A simple install that has been tested on Ubuntu 20.04 is below, if you run into issues see NVM's readme for more info. Before proceeding, verify no node/npm is already installed.

NVM_DIR="${HOME}/.nvm"

git clone --branch v0.39.7 https://github.com/nvm-sh/nvm.git "$NVM_DIR"
cat >> "${HOME}/.bashrc" << EOF

[ -s "$NVM_DIR/nvm.sh" ] && source "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && source "$NVM_DIR/bash_completion"  # This loads nvm bash_completion
EOF
source "$NVM_DIR/nvm.sh"
nvm install 18

If building directly on an AmpliPi, the npm run build step must be set to limit its memory usage with NODE_OPTIONS=--max_old_space_size=768 npm run build.

Congratulations! The Amplipi is now running the software you deployed! You can stop now or continue in order to debug over SSH!

  1. ssh into the AmpliPi with ssh pi@amplipi.local, the default password is raspberry (you can change it to whatever)
  2. Change directory to the development root ~/amplipi-dev (this is where deploy put the software)
  3. To run the amplipi server in debug mode over an ssh connection, run ./scripts/run_debug_webserver it will run a debug webserver on amplipi.local:5000.
  4. Restart amplipi service (it was stopped by ./scripts/run_debug_webserver) with systemctl --user restart amplipi.

Developing on an AmpliPi Controller over SSH

  1. Make a git checkout at ~/amplipi-dev using git checkout https://github.com/micro-nova/AmpliPi ~/amplipi-dev (you may need to delete amplipi-dev if it already exists)
  2. Change directory to amplipi-dev cd ~/amplipi-dev
  3. Make changes using your favorite editor
  4. To run the amplipi server in debug mode, run ./scripts/run_debug_webserver it will run a debug webserver on amplipi.local:5000.
  5. Once you are comfortable with your changes, run ./scripts/configure.py --python-deps --os-deps --display --web. This will install any required dependencies and reconfigure the amplipi web and display services.

Developing on an AmpliPi Controller remotely using vscode

See our remote vscode guide for more information.

Additional setup and notes for testing on Windows

You will need to install the following:

Notes:

  • The latest Windows 10 supports mDNS which we use to easily ssh into amplipi, however we had some problems using WiFi so we suggest a ethernet connection on windows.

Different development setups

Below are a couple of different ways you can start developing for the AmpliPi without an actual system:

  • Mocked out audio and mocked out controller (needs: debian based system such as Pi or Ubuntu)

    Supports:

    • Web interface development
    • API testing
    • Basic Streams testing

  • Mocked out controller (with 4 stereo audio channels), needs: something running Raspberry Pi OS (previously called raspbian)

    Supports:

    • Web interface development
    • API testing
    • Streams integration and testing

    Requires:

  • Actual system

    Supports:

    • Web interface development
    • API testing
    • Streams integration and testing
    • Group and zone configuration
    • Analog Audio input

Developing with a mocked out controller on a debian based os

This is the simplest way to develop new features for AmpliPi without an AmpliPi controller. Optionally you can install some streaming sources for partial streaming testing.

  1. Checkout this repo
  2. (Optional) Install streaming os dependencies with ./scripts/configure.py --os-deps. The dependencies will be installed globally with apt. This is optional since it installs many packages needed by the various streaming sources. It could potentially cause package conflicts on your system.
  3. Install python dependencies to AmpliPi's virtual environment with ./scripts/configure.py --python-deps
  4. Use ./scripts/run_debug_webserver to start the mock server, if the streaming deps were not installed add the --mock-streams flag like ./scripts/run_debug_webserver --mock-streams.

Developing with a mocked out controller (with 4 stereo channel audio) on something running Raspberry Pi OS

  1. Start with a 32-bit version of Rasberry Pi OS. This needs to be older than december 2020 since our system only supports the ALSA audio backend currently.
  2. Connect a cmedia based, usb, 7.1 channel audio device to the pi. We have tested using this one: https://www.amazon.com/Vantec-NBA-200U-External-Channel-Adapter/dp/B004HXGJ3S
  3. Checkout this repo on a linux based system (a git bash shell on windows works fine as well)
  4. Edit config/asound.conf. Uncomment the "Old Prototype" section at the bottom, and comment out the similar configuration above. This should be the configuration needed for the 7.1 channel USB audio card. Depending on the setup the card will either show up as #2 or #3. That needs to be changed on lines 27 and 32. Find the card # using aplay -l | grep "USB Sound Device" and edit those lines to include the correct #.
  5. Execute scripts/deploy USER@HOSTNAME --mock-ctrl or scripts/deploy USER@IP_ADDRESS replacing USER and HOSTNAME/IP_ADDRESS with the appropriate values for the pi device
  6. Over ssh connection, run scripts/run_debug_webserver --mock-ctrl from the ~/amplipi-dev directory.

Installing AmpliPi from scratch on a Pi Compute Module

  1. For a fresh pi compute module, run scripts/bootstrap-pi. All pi compute modules shipped with AmpliPi's have already been configured using this script, so this step should not be necessary. Running the script without any arguments will print the instructions. After this step is done SSH is enabled from a fresh Raspberry Pi OS at [amplipi.local].
  2. [amplipi.local] should now be hosted on your network.