readme.md

Boxel is a wooden box that contains a Raspberry Pi and a 32x32 LED matrix.

A local HTTP server allows any device on the same network to act as a remote controller to choose among several modes: digital clock, weather stats and forecast, digital photo frame, and so on.

• 📸 Making-of & pictures
• 🛠️ Material
• 🔌 Wiring
• 🎛️ Available modes
• 💾 Software installation
• ⚠️ Todos and known issues
• 💡 Credits

Material

• Raspberry Pi with a 40 pin GPIO header (tested with a Pi 2 Model B Rev 1.1)
• 32x32 LED matrix and its DC cable
• 14 female to female jumper wires
• DC to female 2.1mm Jack adapter
• 5V male Jack to male USB adapter (1A)
• Micro USB to USB adapter (2.4A)
• USB to AC adapter (5V 3.4A with 2 ports)
• USB Wi-Fi dongle
• A few wooden planks, screws, small shelf brackets

Wiring

I could not find the original wiring schema that was used for this project, so here is the current one that works (the matrix must be powered with its own cable)

Matrix	R0	G0	B0	Ground	R1	G1	B1	A	B	C	D	CLK	STB	OE
GPIO	23	13	26	6	24	21	19	15	16	18	22	11	7	12

Available modes

• Digital clock (source)
• Netatmo weather report (source)
• Pomodoro (source)
• Random pixels (source)
• Digital frame (source)

Software installation

On the dev machine

Clone the project and install the dependencies:

git clone git@github.com:johansatge/boxel.git
cd boxel/app
npm install

Start the app in dry run (so it doesn't try to initialize the LED matrix):

node app/index.js --dry-run

On the Raspberry Pi

Base install

• Use Raspberry Pi Imager to install the latest Raspbian on the SD card (tested version: 10 Buster)
• From the GUI (startx), configure:
  • The user (pi), current date & time, location
  • The wifi
  • Enable SSH & configure a key if needed
• Disable on-board sound in /boot/config.txt by setting dtparam=audio=off

Node.js

Install Node.js LTS (tested version: node 12.16.2 / npm 6.14.4)

curl -sL https://deb.nodesource.com/setup_12.x | sudo bash -
sudo apt-get install nodejs

Project installation

From the dev machine, sync the app:

sh sync.sh

On the Pi, install the dependencies:

cd /home/pi/boxel-app
npm install

Create a state file and make sure it's writable:

touch /home/pi/boxel-app/.state.json
chmod 777 /home/pi/boxel-app/.state.json
# Todo: check what user is node using to give proper r/w permissions

Create a file to expose Netatmo credentials:

touch /home/pi/boxel-app/.netatmo.json
# The file looks like this:
# {
#   "clientId": "aaaa",
#   "clientSecret": "bbbb",
#   "username": "cccc",
#   "password": "dddd"
# }

Finally, start the app:

sudo node /home/pi/boxel-app/index.js

Or alternatively, start the app on the dev machine in dry run mode. This will start the server but prevent the app from connecting to the matrix:

node index.js --dry-run

Todos and known issues

Todos

• Add a brightness menu
  • A slider somewhere in the UI (in the header?)
  • When the slider is used, store the requested brightness in the app state, and forward it to the matrix
• In the frame mode, if the uploaded image is not 32x32:
  • Crop it to a square format
  • Resize/resample it to 32x32 (client-side)
• Add a sleep button in the header to turn off the matrix without shutting down the Raspberry
  • Easy alternative/first step: add an idle mode that does nothing

Known issues

• Enabling and disabling modes is synchronous (it was easier to implement)
• It means the activation workflow of a mode is limited: it's not possible to validate the input data asynchronously, for instance
• The netatmo mode may break the display if the mode is changed while it's processing (see comment in the code)

Credits

• hzeller/rpi-rgb-led-matrix
• alexeden/rpi-led-matrix (Node binding for the original library)
• Connecting a 16x32 RGB led matrix panel to a Raspberry Pi