update readme.md (#29)

- update GitHub actions - update license 2023 - update readme.md
RobTillaart · Feb 1, 2023 · 2fdb294 · 2fdb294
1 parent d082848
commit 2fdb294
Show file tree

Hide file tree

Showing 8 changed files with 95 additions and 52 deletions.
diff --git a/AS5600.cpp b/AS5600.cpp
@@ -1,7 +1,7 @@
 //
 //    FILE: AS56000.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.3.4
+// VERSION: 0.3.5
 // PURPOSE: Arduino library for AS5600 magnetic rotation meter
 //    DATE: 2022-05-28
 //     URL: https://github.com/RobTillaart/AS5600

diff --git a/AS5600.h b/AS5600.h
@@ -2,7 +2,7 @@
 //
 //    FILE: AS5600.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.3.4
+// VERSION: 0.3.5
 // PURPOSE: Arduino library for AS5600 magnetic rotation meter
 //    DATE: 2022-05-28
 //     URL: https://github.com/RobTillaart/AS5600
@@ -12,7 +12,7 @@
 #include "Wire.h"
 
 
-#define AS5600_LIB_VERSION              (F("0.3.4"))
+#define AS5600_LIB_VERSION              (F("0.3.5"))
 
 //  default addresses
 const uint8_t AS5600_DEFAULT_ADDRESS    = 0x36;

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,13 +5,18 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.3.5] - 2023-02-01
+- update GitHub actions
+- update license 2023
+- update readme.md
+
+
 ## [0.3.4] - 2022-12-22
 - fix #26 edges problem of the experimental cumulative position (CP).
 - decoupled CP from **rawAngle()**
   - now one needs to call **getCumulativePosition()** to update the CP.
 - updated the readme.md section about CP.
 
-
 ## [0.3.3] - 2022-12-19
 - add experimental continuous position.
   - add **getCumulativePosition()**

diff --git a/README.md b/README.md
@@ -13,15 +13,18 @@ Arduino library for AS5600 and AS5600L magnetic rotation meter.
 
 ## Description
 
-### AS5600
+#### AS5600
+
+**AS5600** is a library for an AS5600 / AS5600L based magnetic **rotation** meter.
+More exact, it measures the angle (rotation wrt reference) and not RPM.
+Multiple angle measurements allows one to calculate / estimate the RPM.
 
-**AS5600** is a library for an AS5600 / AS5600L based magnetic rotation meter.
-These sensors are pin compatible (always check datasheet).
+The AS5600 and AS5600L sensors are pin compatible (always check datasheet).
 
 **Warning: experimental**
 
 The sensor can measure a full rotation in 4096 steps.
-The precision is therefore limited to approx 0.1°.
+The precision of the position is therefore limited to approx 0.1°.
 Noise levels are unknown, but one might expect that the sensor is affected by electric
 and or magnetic signals in the environment.
 Also unknown is the influence of metals near the sensor or an unstable 
@@ -30,9 +33,7 @@ or fluctuating power supply.
 Please share your experiences.
 
 
-### Related libraries
-
-Possible interesting related libraries.
+#### Related libraries
 
 - https://github.com/RobTillaart/Angle
 - https://github.com/RobTillaart/AngleConvertor
@@ -46,13 +47,14 @@ The I2C address of the **AS5600** is always 0x36.
 
 The AS5600 datasheet states it supports Fast-Mode == 400 KHz
 and Fast-Mode-Plus == 1000 KHz. 
-Tests with a AS5600L failed at 400 KHz (needs investigation).
+Tests with an AS5600L (UNO) failed at 400 KHz (needs investigation).
 
 The sensor should connect the I2C lines SDA and SCL and the
 VCC and GND to communicate with the processor.
+Do not forget to add the pull up resistors to improve the I2C signals.
 
 
-### DIR pin
+#### DIR pin
 
 From datasheet, page 30 - Direction (clockwise vs. counter-clockwise)
 
@@ -82,7 +84,7 @@ parameter set to **255**, Software Direction Control is enabled.
 See Software Direction Control below for more information.
 
 
-### OUT pin
+#### OUT pin
 
 The sensor has an output pin named **OUT**.
 This pin can be used for an analogue or PWM output signal (AS5600),
@@ -95,7 +97,7 @@ Examples are added to show how to use this pin with **setOutputMode()**.
 See more in the sections Analog OUT and PWM OUT below.
 
 
-### PGO pin
+#### PGO pin
 
 Not tested. ==> Read the datasheet!
 
@@ -109,31 +111,51 @@ See **Make configuration persistent** below.
 
 ## I2C 
 
-### Address
+#### Address
 
 |  sensor  |  address  |  changeable  |
 |:--------:|:---------:|:-------------|
-|  AS5600  |    0x36   | NO           |
-|  AS5600L |    0x40   | YES, check setAddress()  |
+|  AS5600  |    0x36   |  NO          |
+|  AS5600L |    0x40   |  YES, check setAddress()  |
 
 To use more than one **AS5600** on one I2C bus, see Multiplexing below.
 
 The **AS5600L** supports the change of I2C address, optionally permanent.
 Check the **setAddress()** function for non-permanent change. 
 
 
-### Performance
+#### Performance
+
+|     board     |  sensor   |  results         |  notes  |
+|:-------------:|:---------:|:-----------------|:--------|
+|  Arduino UNO  |  AS5600   |  up to 900 KHz.  |  https://github.com/RobTillaart/AS5600/issues/22
+|  Arduino UNO  |  AS5600L  |  up to 300 KHz.  |
+|  ESP32        |  AS5600   |  no data         |
+|  ESP32        |  AS5600L  |  up to 800 KHz   |
+
+No other boards tested yet.
+
+
+#### ESP32 and I2C
+
+When polling the AS5600 with an ESP32 to measure RPM an issue has been reported.
+See https://github.com/RobTillaart/AS5600/issues/28
 
-|    board    |  sensor   |  results        |  notes   |
-|:-----------:|:---------:|:----------------|:---------|
-| Arduino UNO |  AS5600   | up to 900 KHz.  | see #22  |
-| Arduino UNO |  AS5600L  | up to 300 KHz.  |          |
+The problem is that the ESP32 can be blocking for up to one second if there is a
+problem in the connection with the sensor. Using **setWireTimeout()** does not seem
+to solve the problem (2023-01-31). In the issue the goal was to measure the turns 
+of a rotating device at around 3800 RPM. To do this one need roughly 1 angle measurement
+per 5 milliseconds. 
+which  
 
 
 ## Interface
 
+```cpp
+#include "AS5600.h"
+```
 
-### Constants
+#### Constants
 
 Most important are:
 
@@ -159,7 +181,7 @@ See AS5600.h file (and datasheet) for all constants.
 Also Configuration bits below for configuration related ones.
 
 
-### Constructor + I2C
+#### Constructor + I2C
 
 - **AS5600(TwoWire \*wire = &Wire)** Constructor with optional Wire 
 interface as parameter.
@@ -177,7 +199,7 @@ See below.
 - **uint8_t getAddress()** returns the fixed device address 0x36 (AS5600).
 
 
-### Direction
+#### Direction
 
 To define in which way the sensor counts up.
 
@@ -188,7 +210,7 @@ AS5600_COUNTERCLOCK_WISE (1).
 See Software Direction Control below for more information.
 
 
-### Configuration registers
+#### Configuration registers
 
 Please read the datasheet for details.
 
@@ -214,16 +236,17 @@ Returns false if parameter is out of range.
 - **uint16_t getConfigure()** returns the current configuration register a bit mask.
 
 
-| Bit   | short | Description   | Values                                                | 
-|:-----:|:------|:--------------|:------------------------------------------------------|
-| 0-1   |  PM   | Power mode    | 00 = NOM, 01 = LPM1, 10 = LPM2, 11 = LPM3             |
-| 2-3   |  HYST | Hysteresis    | 00 = OFF, 01 = 1 LSB, 10 = 2 LSB, 11 = 3 LSB          |
-| 4-5   |  OUTS | Output Stage  | 00 = analog (0-100%), 01 = analog (10-90%), 10 = PWM  |
-| 6-7   |  PWMF | PWM frequency | 00 = 115, 01 = 230, 10 = 460, 11 = 920 (Hz)           |
-| 8-9   |  SF   | Slow Filter   | 00 = 16x, 01 = 8x, 10 = 4x, 11 = 2x                   |
-| 10-12 |  FTH  | Fast Filter   | Threshold 000 - 111 check datasheet                   |
-| 13    |  WD   | Watch Dog     | 0 = OFF, 1 = ON                                       |
-| 15-14 |       | not used      |
+|  Bit    |  short  | Description     |  Values                                                | 
+|:-------:|:--------|:----------------|:-------------------------------------------------------|
+|  0-1    |  PM     |  Power mode     |  00 = NOM,  01 = LPM1,   10 = LPM2,   11 = LPM3        |
+|  2-3    |  HYST   |  Hysteresis     |  00 = OFF,  01 = 1 LSB,  10 = 2 LSB,  11 = 3 LSB       |
+|  4-5    |  OUTS   |  Output Stage   |  00 = analog (0-100%), 01 = analog (10-90%), 10 = PWM  |
+|  6-7    |  PWMF   |  PWM frequency  |  00 = 115,  01 = 230,    10 = 460,    11 = 920 (Hz)    |
+|  8-9    |  SF     |  Slow Filter    |  00 = 16x,  01 = 8x,     10 = 4x,     11 = 2x          |
+|  10-12  |  FTH    |  Fast Filter    |  Threshold 000 - 111 check datasheet                   |
+|  13     |  WD     |  Watch Dog      |  0 = OFF,    1 = ON                                    |
+|  15-14  |         |  not used       |  
+
 
 The library has functions to address these fields directly.
 The setters() returns false if parameter is out of range.
@@ -246,7 +269,7 @@ In a way one is trading precision for stability.
 - **uint8_t getWatchDog()**
 
 
-### Read Angle
+#### Read Angle
 
 - **uint16_t rawAngle()** returns 0 .. 4095. (12 bits) 
 Conversion factor AS5600_RAW_TO_DEGREES = 360 / 4096 = 0.087890625 
@@ -265,13 +288,13 @@ measurements as floats have only 7 significant digits.
 Verify this for your application.
 - **float getOffset()** returns offset in degrees.
 
-In #14 there is a discussion about **setOffset()**.
+In issue #14 there is a discussion about **setOffset()**.
 A possible implementation is to ignore all values outside the
 -359.99 - 359.99 range.
 This would help to keep the precision high. User responsibility.
 
 
-### Angular Speed
+#### Angular Speed
 
 - **float getAngularSpeed(uint8_t mode = AS5600_MODE_DEGREES)** is an experimental function that returns 
 an approximation of the angular speed in rotations per second.
@@ -301,13 +324,14 @@ with a short interval. The only limitation then is that both measurements
 should be within 180° = half a rotation. 
 
 
-### Cumulative position (experimental)
+#### Cumulative position (experimental)
 
 Since 0.3.3 an experimental cumulative position can be requested from the library.
 The sensor does not provide interrupts to indicate a movement or revolution
-Therefore one has to poll the sensor at a frequency at least 3 times per revolution with **getCumulativePosition()**
+Therefore one has to poll the sensor at a frequency at least **three** times 
+per revolution with **getCumulativePosition()**
 
-The cumulative position consists of 3 parts
+The cumulative position (32 bits) consists of 3 parts
 
 |  bit    |  meaning      |  notes  |
 |:-------:|:--------------|:--------|
@@ -325,7 +349,7 @@ Convenience function.
 The cumulative position does not reset to 0 but to the last known raw angle.
 This way the cumulative position always indicate the (absolute) angle too.
 
-As this code is experimental, names might change in the future.
+As this code is experimental, names might change in the future (0.4.0).
 As the function are mostly about counting revolutions the current thoughts for new names are:
 
 ```cpp
@@ -335,7 +359,7 @@ int32_t resetRevolutions()   replaces resetPosition()
 ```
 
 
-### Status registers
+#### Status registers
 
 - **uint8_t readStatus()** see Status bits below.
 - **uint8_t readAGC()** returns the Automatic Gain Control.
@@ -361,7 +385,7 @@ Please read datasheet for details.
 |  6-7  |       | not used      |                       |
 
 
-### Make configuration persistent.
+## Make configuration persistent.
 
 **USE AT OWN RISK**
 
@@ -384,6 +408,8 @@ and **TWO** times for the AS5600L.
 - **void burnSetting()** writes the MANG register to permanent memory. 
 You can write this only **ONE** time to the AS5600.
 
+**USE AT OWN RISK**
+
 
 ## Software Direction Control
 
@@ -532,12 +558,12 @@ As the I2C address can be changed in the AS5600L, the address is a parameter of
 This is a difference with the AS5600 constructor.
 
 
-### Setting I2C address
+#### Setting I2C address
 
 - **bool setAddress(uint8_t address)** Returns false if the I2C address is not in valid range (8-119).
 
 
-### Setting I2C UPDT
+#### Setting I2C UPDT
 
 UPDT = update  page 30 - AS5600L 
 
@@ -591,6 +617,8 @@ priority is relative.
   - other class hierarchy? 
     - base class with commonalities?
   - just ignore?
+- rename revolution functions (0.4.0)
+
 
 #### Should
 
@@ -613,10 +641,15 @@ priority is relative.
   - 1 minute (need HW)
 - check Timing Characteristics (datasheet)
   - is there improvement possible.
+- investigate why AS5600L failed at 400 KHz I2C
+  - repeatable?
 
 
 #### Could
 
 - add error handling
 - investigate PGO programming pin.
 
+
+#### Wont
+
diff --git a/examples/AS5600_I2C_frequency/AS5600_I2C_frequency.ino b/examples/AS5600_I2C_frequency/AS5600_I2C_frequency.ino
@@ -21,7 +21,12 @@ void setup()
 
   Wire.begin();
 
+  //  UNO
   as5600.begin(4);  //  set direction pin.
+  //  ESP32
+  //  as5600.begin(14, 15);     // no direction pin.
+  //  as5600.setAddress(0x40);  // AS5600L only
+
   as5600.setDirection(AS5600_CLOCK_WISE);  // default, just be explicit.
   int b = as5600.isConnected();
   Serial.print("Connect: ");
@@ -32,7 +37,7 @@ void setup()
 void loop()
 {
   clk += 100000;
-  if (clk >= 800000) clk = 100000;
+  if (clk > 800000) clk = 100000;
   Wire.setClock(clk);
 
   Serial.print(clk);

diff --git a/examples/AS5600_position/AS5600_position.ino b/examples/AS5600_position/AS5600_position.ino
@@ -26,7 +26,7 @@ void setup()
 
   Serial.println(as5600.getAddress());
 
-  // as5600.setAddress(0x40);  // AS5600L only
+  //  as5600.setAddress(0x40);  // AS5600L only
 
   int b = as5600.isConnected();
   Serial.print("Connect: ");

diff --git a/library.json b/library.json
@@ -15,7 +15,7 @@
     "type": "git",
     "url": "https://github.com/RobTillaart/AS5600.git"
   },
-  "version": "0.3.4",
+  "version": "0.3.5",
   "license": "MIT",
   "frameworks": "arduino",
   "platforms": "*",

diff --git a/library.properties b/library.properties
@@ -1,5 +1,5 @@
 name=AS5600
-version=0.3.4
+version=0.3.5
 author=Rob Tillaart <rob.tillaart@gmail.com>
 maintainer=Rob Tillaart <rob.tillaart@gmail.com>
 sentence=Arduino library for AS5600 and AS5600L magnetic rotation meter.