MMS

MMS (at this point a more or less meaningless acronym, but can be interpreted as MilliMeter Slide) is a control system for accurately and semi-automatically positioning some sort of slide using one or two industrial servos in a gantry configuration (specifically using these cheap drivers that have some issues).

A touchscreen UI allows you to move the slide to a certain position and/or define a sequence of distances to repeatedly move to in order. This is useful as an accessory for semi-automating a variety of manual machining processes such as cutting sheet metal or wood to a specific size. The implementation may seem overkill for such a "simple" task which can be attributed to the attempt at combining polish and user-friendliness with flexibility and a powerful feature set.

⚠️ Disclaimer ⚠️

This repository serves the sole purpose of documenting this project and is not a tutorial (at most information or a starting point for others building something similar). I do not claim that this implementation is the best or even the right way to do it. In no way does this work represent a product that claims to satisfy any functionality or safety standards and it should not be used in a production setup as is. Mains voltage and industrial servos are dangerous ;), use any of the provided code and documentation at your own risk.

Repo Structure

The project is divided into two main parts:

• mms_plc_firmware: (Real-Time) PLC firmware for running on the Controllino Maxi PLC (basically an ATMega2560 with 24V IOs)
• mms_ui: (Non-RT) Python-based Touchscreen UI running on a Raspberry Pi 4 for controlling the PLC

Additionally, there are the following other components:

• system: NixOS system configuration for the Raspberry Pi to run the UI application
• resources: Images and other resources to build the system
• mms_schematics: Rough schematics of the electronics used to test this software
• hardware: 3D files and drawings for some test setups
• docs: Collection of datasheets and drawings of internal and 3rd party components.
• data: Development dataset for MMS UI

Production Deployment

The repository relies on some submodules to work properly, so these need to be initialized:

git submodule init
git submodule update

After this, deployment is split into the PLC firmware and Raspberry Pi firmware.

PLC Firmware

To build the PLC firmware, open the mms_plc_firmware folder using PlatformIO.

In src/networking.cpp, edit the IP configuration to what you need.

Connect the PLC via the USB Port to the computer and Build+Upload the firmware using PlatformIO.

MMS Pi OS

The OS running on the Pi is a Kiosk-like NixOS configuration that runs the MMS UI application. Before proceeding, adjust the network configuration in the NixOS config to match what you need. The IP Address of the Pi must be entered on the PLC so the PLC can connect to MMS UI via TCP.

Rebuild the system on an existing deployment

You need to have binfmt aarch64-linux enabled when building on a machine of different architecture.

./rebuild root@<ip_of_pi>

This will automatically rebuild the system on the local machine and deploy it onto the Pi via SSH.

Initial deployment to fresh system

Generate a .img to deploy on the Pi:

You need to have binfmt aarch64-linux enabled when building on a machine of different architecture.

nix build .#images.mmspi

This results in an image file an a result folder.

Next, when using a Compute Module with eMMC, plug in the CM4 board with the eMMC disable jumper set and mount the eMMC on the computer:

nix-shell -p rpiboot 
sudo rpiboot

Now flash the generated img onto the mounted eMMC disk or SD card using RPi Imager or dd or any other way you like. On the first boot, you will have to log in via SSH-key and get the host public key of the newly installed system:

[root@mmspi:~]# cat /etc/ssh/ssh_host_ed25519_key.pub 
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEA4axRPPnE9F+CcRJEf8ob5NDEDWmVRV6jHH219p0nd root@nixos

Copy this key and add it to the secrets.nix host list. Then rekey the secrets files using

agenix -r

in the project root directory. Given that you most likely cannot decrypt my secret file containing the password hash, you must instead replace it with a new file containing your desired password's hash generated using the following command:

mkpasswd -m sha-512

After that, rebuild and deploy the image using ./rebuild.bash as described above. Then reboot the pi and the system should be ready!

Development Setup

PLC Firmware

The PLC firmware is just a PlatformIO project. Make sure all git submodules are initialized, open the mms_plc_firmware folder with PlatformIO and you are ready to go.

MMS UI

To develop for mms_ui, allow direnv in this repository. This automatically creates a dev shell with almost all of the required dependencies installed.

One exception is el_std_py as this is frequently modified alongside the development of MMS UI. To add it, as well as to enable executing MMS UI, create a venv with both packages:

python -m venv .venv
source .venv/bin/activate
pip install -e ./mms_ui
pip install -e /path/to/your/el_std_py/
# alternatively, you can also add el_std_py to the shell, just like it is in the production package.

This only has to be done once, afterwards the venv will be automatically activated in the dev shell. You can then run MMS UI as follows:

python -m mms_ui.main

Or you can use the VSCode launch configuration to debug the application.

License

Source code found in this project is generally licensed under the Apache License Version 2.0. An exception to this are 3rd party libraries and documents included here, which maintain the original license provided by the author as noted in the individual files.