Please note that this app is not ready for prime time just yet and this Read Me may be out of date!
This repository contains the source code for the Operator App, a FastAPI application designed to manage and control Mugsys hardware devices. All GPIO control is handled by Operator to keep hardware related functionality isolated from the primary DECAF api, allowing for increased hardware compatibility.
Requests from the Mugsy frontend are sent to the DECAF API which handles all primary functionality. When a GPIO action is required, DECAF calls Operator to perform the action.
Before you begin, ensure you have the following installed on your system:
To set up the project environment:
Clone the repository:
git clone https://github.com/margyle/operator.git
cd operator
Create and activate a virtual environment (optional but recommended):
python -m venv venv
source venv/bin/activate
python -m venv venv
venv\Scripts\activate
To install the application in editable mode, which is recommended for development purposes:
pip install -e .
This command allows you to modify the source code and see changes without reinstalling the package.
To install the application for production use:
pip install .
This command installs the application as a standard Python package.
To start the FastAPI application, run:
uvicorn operator_app.app:app --reload --host 0.0.0.0 --port 8000
This command will start the FastAPI server with live reloading enabled.
To run tests, run:
pytest
If you are getting import errors, you may need to add your app source to the ENV, run:
export PYTHONPATH=$PYTHONPATH:/path/to/Operator/src
After testing numerous libs to handle the HX711 load cell amps, the best option was found to be the Raspberry Pi HX711 C++ Library by Daniel Robertson (@endail on Github), and its associated Python wrappers for interacting with it from Operator.
Installation: In order to use the Python wrapper we must first install the C++ library:
sudo apt-get install -y liblgpio-dev
pi@raspberrypi:~ $ git clone --depth=1 https://github.com/endail/hx711
pi@raspberrypi:~ $ cd hx711
pi@raspberrypi:~/hx711 $ make && sudo make install
ldconfig
, it should not require any additional actions once completed.Install Python Wrapper:
pip3 install --upgrade hx711-rpi-py
The easiest method to calibrate the scales without the UI is to start Operator and connect to the calibration endpoint in Postman: ws://mugsy-0.local:8000/v1/calibrate-scales/CONE_SCALE
If you want to calibrate the mug platform, just swap out CONE_SCALE for MUG_SCALE in the endpoint’s URL.
Once connected, you will be walked through the calibration process. Here are the steps and the response formatting for each step:
{"unit": “g”}
{"known_weight": 100.00}
{"samples": 15}
{“ready”: true}
{“ready”: true}
After these steps, the endpoint sends a final JSON response with the calibration results, including:
The calibration values are automatically written to the hardware configuration file, ready to be used in any weight related functions.
Contributions to this project are welcome. Please ensure that all pull requests are well-documented and include tests where applicable.
The file src/operator_services/libs/hx711.py
in this project was based on HX711 which is licensed under the BSD 3-Clause License, Copyright (c) 2017, Marcel Zak. Modifications were made to make it compatible with pigpio.
Original Library License: BSD 3-Clause License
Please refer to the original source for the unmodified version and further details about the library.