This project is heavily inspired by numerous preceding LEGO® sorting machines, I'd like to give credit in this post. For background information visit the new blog, old blog or YouTube channel.
This software uses network communication between its components. It's critical to understand that this communication is not secure by default. There is no authentication on messages received, meaning the system blindly trusts any client connected to the message broker. A malicious broker or client on the same broker can send commands that could potentially damage the machine, exploit your system, or harm your network. The security of the entire system depends on the security of the broker and network configuration. To operate this software safely, you must adhere to the following rules:
- Use a Private Network: The communication is not secured by encryption, you must run this software exclusively on a private, isolated network that you fully control.
- Trusted Clients: Ensure that all third-party clients or other software modules connected to the same broker are fully trusted by you.
If you're unsure what any of this means, we strongly advise against using this software.
If you want to build a LEGO® brick sorting machine yourself, I suggest to start with the DIY build instructions / plans. This repository maintains the software stack to operate LEGO® brick sorting machines.
With prerequisites Python 3.11 and Conda installed, setup conda environment:
./update_environment.sh # Linux
update_environment_win.bat # Windows
Adapt local config (currently no adaptions needed):
cp config.json.example config.json
Machine controller (on raspberry pi, connected to motor drivers):
python sorter.py controller [--disable_machine]
Vision service (on alternative PC):
python sorter.py vision --host=RASPBERRY_PI_IP_ADDRESS --collect_class=None
Classification service (on alternative PC):
python sorter.py classification --host=RASPBERRY_PI_IP_ADDRESS --model=models/CLASSIFIER_MODEL.h5
Notification service (on alternative PC):
python sorter.py notification --host=RASPBERRY_PI_IP_ADDRESS
Install git pre-commit hooks for flake8, black and isort usage:
pre-commit install
Run unit tests:
python -m unittest discover -s test -p "test_*.py"
Run static type checking via mypy (type hints are still pretty sparse in the code so mypy support is currently limited):
python -m mypy sorter.py