Operator Docs Quickie

Hey folks, I have updated the Operator docs with the driver install and calibration process for the scales. I will also paste them below. Please note that this process is for folks who are more technical and building up Mugsy code from scratch, or adding new features. The stock Mugsy set up will handle all of this behind the scenes, and a simple UI is provided in the frontend when user input is required. You only have to touch this stuff if you have a reason or desire to.

Also, I have a few events this weekend and will be AFK until late Sunday night. I will be picking up Mugsy again on Monday night with additional code updates going out mid to late week.

Here are the scale set up docs, you can also find them in the Operator readme here: https://github.com/MugsyOS/Operator?tab=readme-ov-file#scale-setup

Scale Setup

Install Libraries

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:

  • In your terminal, enter: sudo apt-get install -y liblgpio-dev

  • If it is not available, manually build and install it:

pi@raspberrypi:~ $ git clone --depth=1 https://github.com/endail/hx711
pi@raspberrypi:~ $ cd hx711
pi@raspberrypi:~/hx711 $ make && sudo make install

  • Run ldconfig , it should not require any additional actions once completed.

Install Python Wrapper:

  • pip3 install --upgrade hx711-rpi-py

Calibrate Scales (headless):

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:

  • Step 1: Request unit

    • Text: "Enter the unit you want to measure the object in (e.g., g, kg, lb, oz):"

    • Asking: The unit of measurement for the object. Mugsy is set up to work with grams, so enter g.

    • Expected response: {"unit": “g”}

  • Step 2: Request known weight

    • Text: "Enter the weight of the object in [unit]:"

    • Asking: The weight of the object you are using to calibrate the scale in grams. It currently expects a float so you should enter the weight to two decimal spots.

    • Expected response: {"known_weight": 100.00}

  • Step 3: Request number of samples

    • Text: "Enter the number of samples to take from the HX711 chip (e.g., 15):"

    • Asking: The number of samples to take from the HX711 chip. We have had great results with a total of 15 samples.

    • Expected response: {"samples": 15}

  • Step 4: Zero the scale

    • Text: "Remove all objects from the scale and then press enter."

    • Asking: Confirmation that all objects have been removed from the scale

    • Expected response: {“ready”: true}

  • Step 5: Measure known weight

    • Text: "Place the object on the scale and then press enter."

    • Asking: Confirmation that the object has been placed on the scale

    • Expected response: {“ready”: true}

After these steps, the endpoint sends a final JSON response with the calibration results, including:

  • known_weight

  • unit

  • raw_value

  • samples

  • reference_unit

  • zero_value

The calibration values are automatically written to the hardware configuration file, ready to be used in any weight related functions.

Ok, hope everyone has a great weekend and I’ll see you in a few days. Cheers!

MComment