From 28e6fd0e43a6f9beb6c80862f48f9c0630492c08 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Sat, 23 Feb 2019 20:28:59 +0100 Subject: [PATCH 1/2] Update documentation --- README.md | 59 ++++++++++++++++++++++++++---------- doc/{backlog.md => notes.md} | 54 ++++++++++++++++++++++++++------- 2 files changed, 86 insertions(+), 27 deletions(-) rename doc/{backlog.md => notes.md} (50%) diff --git a/README.md b/README.md index c384c07..b1e61fe 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,20 @@ # HX711 -An Arduino library to interface the [Avia Semiconductor HX711 24-Bit Analog-to-Digital Converter (ADC)] for Weight Scales. +An Arduino library to interface the [Avia Semiconductor HX711 24-Bit Analog-to-Digital Converter (ADC)] +for reading load cells / weight scales. -It supports the platforms `atmelavr`, `espressif8266`, `espressif32`, -`atmelsam` and `ststm32` by corresponding [PlatformIO] build environments. +It supports the architectures `atmelavr`, `espressif8266`, `espressif32`, +`atmelsam`, `teensy` and `ststm32` by corresponding [PlatformIO] targets. [Avia Semiconductor HX711 24-Bit Analog-to-Digital Converter (ADC)]: http://www.dfrobot.com/image/data/SEN0160/hx711_english.pdf [PlatformIO]: https://platformio.org/ ## Synopsis + +### Blocking mode +The library is usually used in blocking mode, i.e. it will wait for the +hardware becoming available before returning a reading. + ```c++ #include "HX711.h" HX711 loadcell; @@ -31,7 +37,10 @@ Serial.print("Weight: "); Serial.println(loadcell.get_units(10), 2); ``` -For non-blocking mode, use: +### Non-blocking mode +It is also possible to define a maximum timeout to wait for the hardware +to be initialized. This won't send the program into a spinlock when the +scale is disconnected and will probably also account for hardware failures. ``` // 4. Acquire reading without blocking if (scale.wait_ready_timeout(1000)) { @@ -113,19 +122,12 @@ The library has been tested successfully on the following hardware. Thanks, Bogd 5. Adjust the parameter in step 4 until you get an accurate reading. -## Deprecation warning -This library received some spring-cleaning in February 2019, removing -the pin definition within the constructor completely, as this was not -timing safe. (#29) Please use the new initialization flavor as outlined -in the example above. - - ## Build ### All architectures This will spawn a Python virtualenv in the current directory, -install `platformio` into it and then execute `platformio run`. -effectively running all targets defined in `platformio.ini`. +install `platformio` into it and then execute `platformio run`, +effectively building for all environments defined in `platformio.ini`. make build-all @@ -147,7 +149,9 @@ Environment bluepill [SUCCESS] https://gist.github.com/amotl/5ed6b3eb1fcd2bc78552b218b426f6aa -### Specific environment +### Specific architecture +You can run a build for a specific architecture by specifying +the appropriate platform label on the command line. # Build for LoPy4 make build-env environment=lopy4 @@ -156,6 +160,13 @@ https://gist.github.com/amotl/5ed6b3eb1fcd2bc78552b218b426f6aa make build-env environment=feather_m0 +## Deprecation warning +This library received some spring-cleaning in February 2019 (#123), +removing the pin definition within the constructor completely, as +this was not timing safe. (#29) Please use the new initialization +flavor as outlined in the example above. + + ## Credits Thanks to Weihong Guan who started the first version of this library in 2012 already (see [[arduino|module]Hx711 electronic scale kit](http://aguegu.net/?p=1327), @@ -164,14 +175,30 @@ who took over in 2014 and last but not least all others who contributed to this library over the course of the last years, see also `CONTRIBUTORS.rst` in this repository. -### See also +#### See also - https://item.taobao.com/item.htm?id=18121631630 - https://item.taobao.com/item.htm?id=544769386300 ## Similar libraries - There are other libraries around, enjoy: - https://github.com/olkal/HX711_ADC - https://github.com/queuetue/Q2-HX711-Arduino-Library + + +--- + +## Appendix + +### Considerations about real world effects caused by physics +You should consider getting into the details of strain-gauge load cell +sensors when expecting reasonable results. The range of topics is from +sufficient and stable power supply, using the proper excitation voltage +to the Seebeck effect and temperature compensation. + +See also: +- [Overview about real world effects](https://community.hiveeyes.org/t/analog-vs-digital-signal-gain-amplifiers/380/6) +- [Thermoelectric effect](https://en.wikipedia.org/wiki/Thermoelectric_effect) (Seebeck effect) +- Temperature compensation: [Resource collection](https://community.hiveeyes.org/t/temperaturkompensation-fur-waage-hardware-firmware/115), [DIY research](https://community.hiveeyes.org/t/temperaturkompensation-fur-waage-notig-datensammlung/245) +- [Power management for HX711](https://community.hiveeyes.org/t/stromversorgung-hx711/893) diff --git a/doc/backlog.md b/doc/notes.md similarity index 50% rename from doc/backlog.md rename to doc/notes.md index c6b6bfb..5242aba 100644 --- a/doc/backlog.md +++ b/doc/notes.md @@ -1,31 +1,59 @@ -# HX711 library issue summary +# HX711 library notes -## Miscellaneous +## Backlog - [o] Get library into https://www.arduinolibraries.info/ and https://platformio.org/ - [o] Maybe use constructor-based initialization again? + It does not necessarily need to starting talking to the hardware yet! - [o] Unify critical sections / interrupt disabling between platforms? https://github.com/esp8266/Arduino/issues/2218 -- [o] Q: Would `delay(1)` be better than `delay(0)`? - A: even delay(0) will work. Should be as often as you can spare, but not more than 100ms let's say - -- https://github.com/esp8266/Arduino/issues/2240#issuecomment-230874704 -- [o] Pulling all together - https://github.com/hiveeyes/HX711/tree/spring-cleaning -- [o] Drop a line at https://github.com/aguegu/ardulibs/issues/3 re. support for Arduino Due +- [o] Check out https://github.com/mmarchetti/DirectIO +### Scan more forks + +- https://github.com/bigujun/HX711 +- https://github.com/OpenCamper/HX711 +- https://github.com/compugician/HX711-multi +- https://github.com/CasualTriangle/HX711-multi +- https://github.com/joeybane/HX711-multi +- https://github.com/polmes/HX711-multi +- https://github.com/knifter/HX711 + +See also + +- https://github.com/newAM/LoadCellOccupany + + +### Add links to pin mappings of popular chips +- https://stackoverflow.com/questions/42022000/which-pins-should-i-take-for-i2c-on-arduino-uno/42022566 +- https://www.arduino.cc/en/Hacking/PinMapping32u4 +- https://www.arduino.cc/en/Hacking/PinMappingSAM3X +- https://www.avdweb.nl/arduino/samd21/samd21-variant +- https://techtutorialsx.com/2017/04/02/esp8266-nodemcu-pin-mappings/ +- https://github.com/esp8266/Arduino/issues/584 +- https://www.arduino.cc/en/Hacking/Atmega168Hardware +- https://www.arduino.cc/en/Hacking/PinMapping168 + + +--- + + +# Spring-cleaning issue summary + +https://github.com/hiveeyes/HX711/tree/spring-cleaning ## AVR - [x] AVR interrupt safety https://github.com/bogde/HX711/pull/62 - - ## ARM/SAMD ### Teensy 3.x - [x] Thomas O Fredericks https://github.com/bogde/HX711/pull/96 +### Arduino Due +- [x] Drop a line at https://github.com/aguegu/ardulibs/issues/3 re. support for Arduino Due ## Espressif @@ -42,11 +70,16 @@ - [x] https://github.com/bogde/HX711/issues/89 ### ESP8266 WDT +- [o] https://github.com/bogde/HX711/issues/67 - [x] https://github.com/bogde/HX711/issues/73 - [x] https://github.com/bogde/HX711/pull/81 - [x] https://github.com/bogde/HX711/pull/86 - [x] https://github.com/bogde/HX711/issues/120 - [x] https://github.com/bogde/HX711/issues/101 +- [o] https://github.com/Skaronator/ESP8266-Load-Cell/issues/6 +- [x] Q: Would `delay(1)` be better than `delay(0)`? + A: even delay(0) will work. Should be as often as you can spare, but not more than 100ms let's say + -- https://github.com/esp8266/Arduino/issues/2240#issuecomment-230874704 ### ESP8266 lacking pin mapping - [x] https://github.com/bruhautomation/ESP-MQTT-JSON-Multisensor/issues/14 @@ -54,7 +87,6 @@ - [x] https://github.com/wemos/D1_mini_Examples/issues/21 - [x] https://github.com/esp8266/Arduino/blob/master/variants/nodemcu/pins_arduino.h - ### ESP32 too fast - [x] https://github.com/lemio/HX711 - [x] https://github.com/bogde/HX711/issues/75 From f1e5a6bd30fe0a0a4a8cd1f61fe643c19e3a54f7 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Sat, 23 Feb 2019 20:29:34 +0100 Subject: [PATCH 2/2] Extend hardware support notes in README --- CONTRIBUTORS.md | 4 ++-- README.md | 13 ++++++++----- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index 93af465..4118ea4 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -12,8 +12,8 @@ Listed in the order of appearance. - Geert Roumen et al.: ESP32 support - Thomas O Fredericks: Support for Teensy 3.2 and non-blocking readings - Ahmad Elbadri: Improve ESP8266 stability -- Andreas Motl: Bookkeeping, multiarch support -- The Hiveeyes Developers: Spring-cleaning 2019 +- Andreas Motl: Spring cleaning, multiarch support +- Clemens Gruber: Hardware testing - Many bits and pieces by countless people from the community, see also "doc/backlog.rst" in the repository. diff --git a/README.md b/README.md index b1e61fe..c4848a5 100644 --- a/README.md +++ b/README.md @@ -67,11 +67,14 @@ See `examples` directory in this repository. ## Hardware support -The library has been tested successfully on the following hardware. Thanks, Bogdan! -- Arduino Uno ([ATmega328]) -- WeMos D1 mini ([ESP8266]) -- ESP32 DEVKIT V1 ([ESP32]) -- STM32F103C8T6 STM32 Blue Pill Board ([STM32 F1], [Cortex-M3]) +The library has been tested successfully on the following hardware. + +- [ATmega328]: Arduino Uno +- [ESP8266]: WeMos D1 mini, Adafruit HUZZAH +- [ESP32]: ESP32 DEVKIT V1, Heltec WiFi Kit 32, Adafruit Feather HUZZAH32 +- [STM32 F1] ([Cortex-M3]): STM32F103C8T6 STM32 Blue Pill Board + +Thanks, @bogde and @ClemensGruber! [ATmega328]: https://en.wikipedia.org/wiki/ATmega328 [ESP8266]: https://en.wikipedia.org/wiki/ESP8266