Table of Contents

1. Introduction
2. Setting Up Your Development Environment
3. Understanding the Code Structure
4. Basic Customizations
5. Advanced Customizations
6. Uploading Your Code
7. Troubleshooting

1. Introduction

The Lightbox is a versatile device powered by a Raspberry Pi Pico W, featuring a 16×16 RGB LED matrix. By modifying its open-source code, you can create custom displays, add new features, and enhance its functionality. This guide will walk you through the process of setting up your development environment, understanding the code, and making your first customizations.

Please be aware of the somewhat limited resources on the Raspberry Pi Pico W in combination with Python.

2. Setting Up Your Development Environment

Tools You’ll Need:

• Thonny IDE: An easy-to-use integrated development environment (IDE) perfect for beginners. Download it from thonny.org.
• USB Cable: To connect your Lightbox to your computer.

Steps:

1. Download and Install Thonny:

   • Visit thonny.org and download the appropriate version for your operating system.
   • Follow the installation instructions to set up Thonny on your computer.

2. Connect Your Lightbox:

   • Use the included USB cable to connect your Lightbox to your computer.
   • Ensure your Lightbox is powered on.

3. Open Thonny:

   • Launch Thonny IDE.
   • Thonny should automatically detect your Raspberry Pi Pico W. If not, go to Tools > Options > Interpreter and select MicroPython (Raspberry Pi Pico).

3. Understanding the Code Structure

The Lightbox software consists of several files and folders. Here’s a brief overview:

• data/: Configuration files such as location, temperature units, etc.
• figures/: Default figures like emojis and weather symbols in PPM P3 format.
• images/: Stores images uploaded through the website.
• lib/: Essential libraries for various functionalities.
• web/: HTML documents provided by the local server.
• events.py: Controls the event loop and the images displayed based on button presses.
• main.py: The main script where the program starts.
• weather.py: Stores current weather data.

4. Basic Customizations

Example: Displaying Custom Text

1. 1. 1. Open events.py:

         • In Thonny, navigate to the events.py file in the Lightbox’s file structure.

      2. Add a New Button Event:

         • Locate the section where button events are handled. Add a new event to display custom text:
           python

           elif button_count == 6:
my_lightbox.show_text("Hello World", (255, 255, 255), 0)


      3. Save and Test:

         • Save your changes in Thonny.
         • Unplug and replug the Lightbox to reboot it and see your custom text display.

5. Advanced Customizations

Creating Custom Animations

1. Open rgb_matrix.py:

   • This file contains methods for controlling the LED matrix.

2. Define a New Animation:

   • Create a new function to define your animation pattern:
     
     python

     def custom_animation():
for x in range(16):
for y in range(16):
my_lightbox.set_pixel_color(x, y, (x*16, y*16, 128))
my_lightbox.show()


3. Call Your Animation:

   • Modify the events.py to call your new animation on a specific button press:
     
     python

     elif button_count == 7:
custom_animation()


4. Save and Test:

   • Save your changes and reboot the Lightbox to see your custom animation.

6. Uploading Your Code

1. Save Your Changes:

   • Ensure all changes are saved in Thonny.

2. Disconnect and Reconnect:

   • Unplug the Lightbox from your computer and plug it back in to reboot.

3. Test Your Customizations:

   • Verify that your changes are working as expected.

7. Troubleshooting

Common Issues and Solutions:

• LED Matrix Not Lighting Up:

  • Check power connections and ensure the USB cable is properly connected.
  • Ensure all connections on the circuit board are seated correctly.

• Unable to Connect to Wi-Fi:

  • Verify the SSID and password.
  • Restart the Lightbox and your router.
  • Press and hold the reset button on the back of the Lightbox for 5 seconds to reset Wi-Fi settings.