DIY On-Air-Display controlled by a REST-API

This is the repository for a DIY on-air-display using a MAX7219 8x32 LED matrix controlled by a Raspberry Pico W running a micropython REST-API using Microdot.

Setup

Parts

• MAX7219 8x32 LED matrix
• Raspberry Pico W
• Push-Button
• 5V Micro-USB power-source or USB cable
• Wires
• Casing

Wiring

Casing

I created a simple 3d printed case using OnShape you can use and change to your desired needs. By default it fits the display, RPi and the button meantioned above and you can mount it to the wall. I used a 3mm translucent white acrylic glas to cover the front, but this is oc optional and has only an aesthetic purpose.

Configuration

Make a copy of config.sample.json, name it config.json and apply your configs, like your WiFi credentials etc. .

Flash your Raspberry Pi Zero W with the latest Micropython version (instructions on page).

Upload all files to the root folder of the Raspberry Pi Zero W.

After that you can unmount your Pi and plug it into a suitable power-source. The device should power-up instantly and show its state on the display until it is connected.

When it is connected the display initially shows the given IP address. But you should also be able to use the hostname set in the configs (default: http://on-air-bulb).

Now the device is running and accessible via it's API and the button.

API Docs

GET /on Turn the default image on

Parameters

None

Responses

http-code	content-type	response
200	application/json; charset=UTF-8	JSON

Example cURL

 curl -X GET http://192.168.0.111/on

GET /on/:text Turn any text value on

Parameters

name	type	data-type	description
text	required	string (url-encoded)	the text-string you want to display, if it is longer than 4 letters it will scroll back and forth

Responses

http-code	content-type	response
200	application/json; charset=UTF-8	{"success": true, "state": 1}

Example cURL

 curl -X GET http://192.168.0.111/on/Hello%20World

GET /off Turn the display off

Parameters

None

Responses

http-code	content-type	response
200	application/json; charset=UTF-8	{"success": true, "state": 0}

Example cURL

 curl -X GET http://192.168.0.111/off

GET /toggle Toggle the default image

Parameters

None

Responses

http-code	content-type	response
200	application/json; charset=UTF-8	{"success": true, "state": 1}

Example cURL

 curl -X GET http://192.168.0.111/toggle

GET /toggle/:text Toggle any text value

Parameters

name	type	data-type	description
text	required	string (url-encoded)	the text-string you want to display, if it is longer than 4 letters it will scroll back and forth

Responses

http-code	content-type	response
200	application/json; charset=UTF-8	{"success": true, "state": 1}

Example cURL

 curl -X GET http://192.168.0.111/toggle/hallo%20welt

GET /brightness/:value Set the brightness of the display

Parameters

name	type	data-type	description
brightness	required	int	set it to a value between 1 and 15, default: 1

Responses

http-code	content-type	response
200	application/json; charset=UTF-8	JSON

Example cURL

 curl -X GET http://192.168.0.111/brightness/5

GET /brightness Reset the brightness value

Parameters

None

Responses

http-code	content-type	response
200	application/json; charset=UTF-8	{"success": true, "state": 1}

Example cURL

 curl -X GET http://192.168.0.111/brightness

Apple Shortcut

I made this small shortcut using the Shortcut feature of MacOS and iOS – this way you can easily call it from any widget and/or from your home-screen. You can change the target URL if needed, by default it is the hostname set in the configs.json (Default: on-air-bulb).

Create a custom image (transform image into byte_array)

By default the byte_array representations of the image-0.png and image-1.png in the root folder in src/image.py is displayed after another in an short interval (blinking animation).

To create a custom images follow these steps:

1. install pillow library (image-library):

   pip3 install pillow

2. create your monochrome (black and white, with a background) PNG images in the dimensions of 8x32px and replace the image-0.png and image-1.png in the root folder
3. run the image2bytearray script in the /scripts folder:

   python3 scripts/image2bytearray.py

4. the src/image.py should now be updated with the byte_array representation of your image

---

License

This project is licensed under the GNU General Public License v3.0.