BRICKMASTER2

Summary

A (Circuit)Python application for controlling relays and devices. The most important of which are, of course, Legos.

Project Goals

• Provide a common interface for a variety of devices
• Be able to do cool automations with connected devices (ie: Saturn 5 launch simulation)
• Teach myself some more python (and hardware, and MQTT)

Future Features

• Option to load config from a remote site (ie: web directory)

Latest Updates - V0.5.1

• Debugged issues with client reconnection when the broker goes away (ie: restarts)
• Discovery and Status messages are now retained, which allows devices/entities and their status to be maintained across HA restarts. No more disappearing devices.
• Added new MQTT 'log' option to control logging of the base MQTT client. This is a deep debug option, should really only be needed for debugging.
• Fixed indicator LEDs - those broke at some point - and rewrote them to use CtrlGPIO control objects for consistency.
• Included and tested example systemd units for Linux installs.
• Updated CircuitPython 'code.py' startup file to be smarter and behave as a parallel to the cli invoker on Linux.
• Reorganized with an eye towards packaging. Will learn how to do that at some point.
• Cleaned up some settings and updated documentation.

Latest Updates - V0.5.0

Having struggled with CircuitPython/Adafruit-MiniMQTT stability issues, I have refactored the whole network module and split based on platform. Brickmaster2 on linux will now use the very robust PAHO MQTT, which I also use in my other project, CobraBay. This leads to some code bloat. Notes on how to deploy based on platform are below.

Supported Platforms

• Raspberry Pi OS (Bookworm) - Specifically on the Pi Zero W. Other Pis should work just fine, just aren't tested.
• CircuitPython 9 - CircuitPython 8 is no longer being tested.
  • Adafruit Metro M4 Airlift - Default pystack size on this board is 1536, which should be raised to at least
  • 4096. Given notable memory limitations of this board I may stop testing in the near future. Requires a pystack value of at least 4096, possibly more depending on your control configuration. The ESP32 line or possibly the Metro M7 Airlift would be recommended instead.
  • Adafruit ESP32 Feather v2

Feature set is intended to be 1:1 between CPython and CircuitPython. Documentation notes where this is not true due to platform limitations.

Installation

Linux

Assumes Raspberry Pi OS/Rasbian on a Pi.

Probably works for other Linux versions, but not tested, adapt as appropriate.

1. Download the code from github:

   wget https://github.com/chrisgilldc/brickmaster2/archive/refs/heads/main.zip

2. Extract the file. This will put code into ~/brickmaster2-main:

   unzip main.zip

3. Create a venv for brickmaster.

   python3 -m venv ~/.env_bm2

4. Enter the python venv.

   source ~/.env_bm2/bin/activate

5. Install all the python requirements.

   pip3 install -r ~/brickmaster2-main/requirements.txt

6. Create a config file. You can do this from scratch or copy a file from ~/brickmaster2-main/hwconfigs/, which has starting configs for BrickMaster Hardware. By default, the systemd unit will try to load ~/config.json.

7. Create a scripts directory separate from the distribution. This will make sure any custom scripts don't get overwritten in future updates.

   mkdir ~/scripts

   cp -R ~/brickmaster2-main/scripts/* ~/scripts

8. Make a user systemd directory. This isn't created by default on a freshly installed system.

   mkdir -p ~/.config/systemd/user

9. Copy the example systemd unit to ~/.config/systemd/user.

   cp ~/brickmaster2-main/examples/brickmaster2.service ~/.config/systemd/user

10. If your config file is somewhere other than ~/config.json, update the unit file to point to that file. Edit the ExecStart line with the full path of the config file.

11. Have systemd reload the user units so brickmaster2 is available.

    systemctl --user daemon-reload

12. Start brickmaster.

    systemctl --user start brickmaster2.service

13. Check the status of the unit. Be sure the active line says active (running).

    systemctl --user status brickmaster2.service

14. If it started successfully, enable the unit.

    systemctl --user enable brickmaster2.service

15. Enable linger for the user. This will start the user's systemd instance on system boot and in turn start brickmaster2.

    sudo loginctl enable-linger pi

CircuitPython

Requirements

• CircuitPython 9. Tested on 9.0.5. Later versions should work fine.
  • If your board is not on CP9, update it. Updates can be found here.
• The current CircuitPython 9 Library Bundle. Use libraries from here unless otherwise specified.
• Adafruit MiniMQTT at least 7.9.0.
• If you're using an ESP32 SPI board (ie: Metro M4/M7), use at least Adafruit ESP32SPI at least 8.4.0.

Install Process

1. Download the package from github.

   wget https://github.com/chrisgilldc/brickmaster2/archive/refs/heads/main.zip

2. Extract the package. The package location will be referred to here as "brickmaster2-main" (wherever you have it).

3. Copy "brickmaster2-main/src/brickmaster2" to your circuitpython board's lib directory.

4. Copy "brickmaster2-main/circuitpy-code.py" to your circuitpython board's root directory as code.py.

5. Copy the following libraries from the bundle into the board's lib directory.

   • adafruit_aw9523.mpy
   • adafruit_connection_manager.mpy
   • adafruit_ht16k33
   • adafruit_logging.mpy
   • adafruit_register

6. Copy the adafruit_minimqtt libarary into the board's lib directory.

7. If you're using an ESP32 SPI board, copy the current esp32spi library into the board's lib directory

8. Create a config file. You can do this from scratch or copy a file from brickmaster2-main/hwconfigs/, which has starting configs for BrickMaster Hardware. Place the config file in the board's root directory.

9. Create a settings.toml file. You can start with brickmaster2-main/examples/settings.toml.

   • Fill in all the required parameters with your SSID and Password.
   • An increased, 4Mb PYSTACK size is set by default in the example. This is tested as good on the Metro M4 Airlift.

10. Connect to the serial console (via USB or Web Workflow, depending) and monitor startup.