Metadata-Version: 2.1
Name: serial-weighing-scale
Version: 0.0.6
Summary: serial_weighing_scale
Home-page: https://github.com/larsrollik/SerialWeighingScale
Author: Lars B. Rollik
Author-email: L.B.Rollik@protonmail.com
License: BSD 3-Clause License
        
        Copyright (c) 2021, Lars B. Rollik
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Platform: UNKNOWN
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Provides-Extra: dev
License-File: LICENSE

# Serial Weighing Scale
Arduino-based cheap precision weighing scale for readout via serial communication.

***

Precision weighing scales that include serial port communication usually come at considerable cost. This project showcases an affordable alternative.
Using readily available electronics parts, the scale's measurements can be read via serial communication by a simple Python class.


_Note:_ The design could easily be extended with an Arduino display to show the measurements.


### Bill of Materials
- Arduino Uno (including USB-A to USB-B cable)
- Load cell amplifier HX711 (Sparkfun), e.g. from mouser.co.uk: 474-SEN-13879
- Load cell (100g and 500g cells used), e.g. from mouser.co.uk: 474-SEN-14727 or 474-SEN-14728
- Jumper wires, pin headers, nylon spacers for electronics
- Acrylic or other material of choice for case and load cell mount
- HX711 arduino library from [olkal/HX711_ADC](https://github.com/olkal/HX711_ADC)


### Build
1. Load .ino onto Arduino
2. Assemble electronics, e.g. as described in this [HX711 wiring tutorial]
3. Print 3D components from [drawings](./drawings_for_3D_printing) (Drawings named `model` are only for design, no need to print these)
4. Move electronics into case
5. Calibrate scale via Arduino IDE serial monitor commands. See below for communication protocol for calibration.


### Usage
1. Connect scale via USB to machine that is going to read the measurements from the scale
2. Interact via python `SerialScale` object:


##### Open connection with `SerialWeighingScale` object & perform standard operations on it
```python
import numpy as np
import time

from serial_weighing_scale import SerialWeighingScale

serial_port = "/dev/ttyACM0"  # for Unix systems. "COM1" on Windows systems
scale = SerialWeighingScale(port=serial_port)

while not scale.scale_is_ready():
    time.sleep(.1)

# Perform standard operations
scale.tare_scale()  # Tare scale
scale.read_weight()  # Take single measurement
scale.read_weight_repeated(n_readings=5)  # Get n readings
scale.read_weight_reliable(n_readings=5, measure=np.mean)  # Get statistic of n readings

```

##### Open connection by testing specific serial ports sequentially
```python
import time

from serial_weighing_scale import connect_serial_scale

scale = connect_serial_scale(test_ports=["/dev/ttyACM0", "/dev/ttyACM1"])
while not scale.scale_is_ready():
    time.sleep(.1)

```

##### Not yet implemented: Calibrate scale via python
```python
import time

from serial_weighing_scale import connect_serial_scale

scale = connect_serial_scale(test_ports=["/dev/ttyACM0", "/dev/ttyACM1"])
while not scale.scale_is_ready():
    time.sleep(.1)

known_mass = 45.05  # weight [gram] of object used for claibration
scale.calibrate(known_mass=known_mass)
```


### Communication protocol for messages between python and Arduino

- Tare scale: send "t" -> Tare scale & Arduino confirms with "t"
- Read scale: send "w" -> Arduino returns latest reading
- Calibrate scale: send "c" + weight of known mass
  - Arduino confirms by sending known mass value back
  - Send "a" once known mass was placed on scale -> Arduino performs calibration & returns new calibration factor that needs to be added to `serial_scale.ino`


### TODO
- [ ] Add calibration routine to .ino & .py
- [ ] Add test curve to .py

### Contributors
Code & electronics by Lars Rollik.
Scale 3D printing drawings by Simon Townsend ([Advanced Manufacturing FabLabs], Sainsbury Wellcome Centre).
Thanks to Benjamin Hahl for useful input on the design.

[Advanced Manufacturing FabLabs]: https://www.sainsburywellcome.org/web/content/fablab
[HX711 wiring tutorial]: https://learn.sparkfun.com/tutorials/load-cell-amplifier-hx711-breakout-hookup-guide


