Merge pull request #127 from hiveeyes/spring-cleaning

Update documentation

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.
 

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)) {
@@ -58,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
@@ -113,19 +125,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 +152,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 +163,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 +178,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)

doc/backlog.md → 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,19 +70,23 @@
 - [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
 - [x] https://github.com/witnessmenow/simple-arduino-crypto-display/issues/2
 - [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