add error handling (#56)

- add experimental error handling
- add **int lastError()** so user can check the status of last I2C actions.
- update readme.md
- update examples
- minor edits

AS5600.cpp

@@ -1,7 +1,7 @@
 //
 //    FILE: AS56000.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.5.1
+// VERSION: 0.6.0
 // PURPOSE: Arduino library for AS5600 magnetic rotation meter
 //    DATE: 2022-05-28
 //     URL: https://github.com/RobTillaart/AS5600
@@ -509,29 +509,55 @@ int32_t AS5600::resetCumulativePosition(int32_t position)
 }
 
 
+int AS5600::lastError()
+{
+  int value = _error;
+  _error = AS5600_OK;
+  return value;
+}
+
+
 /////////////////////////////////////////////////////////
 //
 //  PROTECTED AS5600
 //
 uint8_t AS5600::readReg(uint8_t reg)
 {
+  _error = AS5600_OK;
   _wire->beginTransmission(_address);
   _wire->write(reg);
-  _error = _wire->endTransmission();
-
-  _wire->requestFrom(_address, (uint8_t)1);
+  if (_wire->endTransmission() != 0)
+  {
+    _error = AS5600_ERROR_I2C_READ_0;
+    return 0;
+  }
+  uint8_t n = _wire->requestFrom(_address, (uint8_t)1);
+  if (n != 1)
+  {
+    _error = AS5600_ERROR_I2C_READ_1;
+    return 0;
+  }
   uint8_t _data = _wire->read();
   return _data;
 }
 
 
 uint16_t AS5600::readReg2(uint8_t reg)
 {
+  _error = AS5600_OK;
   _wire->beginTransmission(_address);
   _wire->write(reg);
-  _error = _wire->endTransmission();
-
-  _wire->requestFrom(_address, (uint8_t)2);
+  if (_wire->endTransmission() != 0)
+  {
+    _error = AS5600_ERROR_I2C_READ_2;
+    return 0;
+  }
+  uint8_t n = _wire->requestFrom(_address, (uint8_t)2);
+  if (n != 2)
+  {
+    _error = AS5600_ERROR_I2C_READ_3;
+    return 0;
+  }
   uint16_t _data = _wire->read();
   _data <<= 8;
   _data += _wire->read();
@@ -541,21 +567,29 @@ uint16_t AS5600::readReg2(uint8_t reg)
 
 uint8_t AS5600::writeReg(uint8_t reg, uint8_t value)
 {
+  _error = AS5600_OK;
   _wire->beginTransmission(_address);
   _wire->write(reg);
   _wire->write(value);
-  _error = _wire->endTransmission();
+  if (_wire->endTransmission() != 0)
+  {
+    _error = AS5600_ERROR_I2C_WRITE_0;
+  }
   return _error;
 }
 
 
 uint8_t AS5600::writeReg2(uint8_t reg, uint16_t value)
 {
+  _error = AS5600_OK;
   _wire->beginTransmission(_address);
   _wire->write(reg);
   _wire->write(value >> 8);
   _wire->write(value & 0xFF);
-  _error = _wire->endTransmission();
+  if (_wire->endTransmission() != 0)
+  {
+    _error = AS5600_ERROR_I2C_WRITE_0;
+  }
   return _error;
 }
 

AS5600.h

@@ -2,7 +2,7 @@
 //
 //    FILE: AS5600.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.5.1
+// VERSION: 0.6.0
 // PURPOSE: Arduino library for AS5600 magnetic rotation meter
 //    DATE: 2022-05-28
 //     URL: https://github.com/RobTillaart/AS5600
@@ -12,7 +12,8 @@
 #include "Wire.h"
 
 
-#define AS5600_LIB_VERSION              (F("0.5.1"))
+#define AS5600_LIB_VERSION              (F("0.6.0"))
+
 
 //  default addresses
 const uint8_t AS5600_DEFAULT_ADDRESS    = 0x36;
@@ -36,6 +37,17 @@ const uint8_t AS5600_MODE_DEGREES       = 0;
 const uint8_t AS5600_MODE_RADIANS       = 1;
 const uint8_t AS5600_MODE_RPM           = 2;
 
+
+//  ERROR CODES
+const int     AS5600_OK                 = 0;
+const int     AS5600_ERROR_I2C_READ_0   = -100;
+const int     AS5600_ERROR_I2C_READ_1   = -101;
+const int     AS5600_ERROR_I2C_READ_2   = -102;
+const int     AS5600_ERROR_I2C_READ_3   = -103;
+const int     AS5600_ERROR_I2C_WRITE_0  = -200;
+const int     AS5600_ERROR_I2C_WRITE_1  = -201;
+
+
 //  CONFIGURE CONSTANTS
 //  check datasheet for details
 
@@ -202,7 +214,7 @@ class AS5600
   //  void burnSetting();
 
 
-  //  Experimental 0.1.2 - to be tested.
+  //  EXPERIMENTAL 0.1.2 - to be tested.
   //  approximation of the angular speed in rotations per second.
   //  mode == 1: radians /second
   //  mode == 0: degrees /second  (default)
@@ -220,6 +232,9 @@ class AS5600
   //  returns last position.
   int32_t  resetCumulativePosition(int32_t position = 0);
 
+  //  EXPERIMENTAL 0.5.2
+  int      lastError();
+
 
 protected:
   uint8_t  readReg(uint8_t reg);
@@ -230,7 +245,7 @@ class AS5600
   uint8_t  _address         = AS5600_DEFAULT_ADDRESS;
   uint8_t  _directionPin    = 255;
   uint8_t  _direction       = AS5600_CLOCK_WISE;
-  uint8_t  _error           = 0;
+  int      _error           = AS5600_OK;
 
   TwoWire*  _wire;
 

CHANGELOG.md

@@ -5,12 +5,20 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.6.0] - 2024-01-25
+- add experimental error handling
+- add **int lastError()** so user can check the status of last I2C actions.
+- update readme.md
+- update examples
+- minor edits
+
+----
+
 ## [0.5.1] - 2023-12-31
 - fix #51, add **increaseOffset(float degrees)**
 - update keywords.txt
 - update readme.md (several cleanups)
 
-
 ## [0.5.0] - 2023-12-07
 - refactor API, begin()
 - update readme.md

README.md

@@ -118,6 +118,7 @@ See more in the sections Analog OUT and PWM OUT below.
 
 
 ##### Note: (From Zipdox2 - See issue #36)
+
 Some AS5600 modules seem to have a resistor between **PGO** and **GND**.
 This causes the AS5600 to disable the output (to use it for programming, see datasheet). 
 This resistor needs to be removed to use the **OUT** pin.
@@ -137,6 +138,8 @@ See **Make configuration persistent** below.
 
 ## I2C 
 
+The I2C address of the **AS5600** is always 0x36.
+
 #### Address
 
 |  sensor  |  address  |  changeable  |
@@ -150,6 +153,32 @@ The **AS5600L** supports the change of I2C address, optionally permanent.
 Check the **setAddress()** function for non-permanent change. 
 
 
+#### I2C multiplexing
+
+Sometimes you need to control more devices than possible with the default
+address range the device provides.
+This is possible with an I2C multiplexer e.g. TCA9548 which creates up 
+to eight channels (think of it as I2C subnets) which can use the complete 
+address range of the device. 
+
+Drawback of using a multiplexer is that it takes more administration in 
+your code e.g. which device is on which channel. 
+This will slow down the access, which must be taken into account when
+deciding which devices are on which channel.
+Also note that switching between channels will slow down other devices 
+too if they are behind the multiplexer.
+
+- https://github.com/RobTillaart/TCA9548
+
+Alternative could be the use of a AND port for the I2C clock line to prevent 
+the sensor from listening to signals on the I2C bus. 
+
+Finally the sensor has an analogue output **OUT**.
+This output could be used to connect multiple sensors to different analogue ports of the processor.
+
+**Warning**: If and how well this analog option works is not verified or tested.
+
+
 #### Performance
 
 |     board     |  sensor   |  results         |  notes  |
@@ -439,6 +468,40 @@ Please read datasheet for details.
 |  6-7  |       | not used      |                       |
 
 
+#### Error handling
+
+Since 0.5.2 the library has added **experimental** error handling.
+For now only lowest level I2C errors are checked for transmission errors.
+Error handling might be improved upon in the future.
+
+Note: The public functions do not act on error conditions.
+This might change in the future.
+So the user should check for error conditions.
+
+```cpp
+int e = lastError();
+if (e != AS5600_OK)
+{
+  //  handle error
+}
+```
+
+
+- **int lastError()** returns the last error code.
+After reading the error status is cleared to **AS5600_OK**.
+
+
+|  Error codes              |  value  |  notes    |
+|:--------------------------|:-------:|:----------|
+|  AS5600_OK                |     0   |  default  |
+|  AS5600_ERROR_I2C_READ_0  |  -100   |
+|  AS5600_ERROR_I2C_READ_1  |  -101   |
+|  AS5600_ERROR_I2C_READ_2  |  -102   |
+|  AS5600_ERROR_I2C_READ_3  |  -103   |
+|  AS5600_ERROR_I2C_WRITE_0 |  -200   |
+|  AS5600_ERROR_I2C_WRITE_1 |  -201   |
+
+
 ## Make configuration persistent. BURN
 
 #### Read burn count
@@ -599,20 +662,6 @@ with enough precision to get the max resolution.
 When PWM OUT is selected **readAngle()** will still return valid values.
 
 
-## Multiplexing
-
-The I2C address of the **AS5600** is always 0x36.
-
-To use more than one **AS5600** on one I2C bus, one needs an I2C multiplexer, 
-e.g. https://github.com/RobTillaart/TCA9548.
-Alternative could be the use of a AND port for the I2C clock line to prevent 
-the sensor from listening to signals on the I2C bus. 
-
-Finally the sensor has an analogue output **OUT**.
-This output could be used to connect multiple sensors to different analogue ports of the processor.
-
-**Warning**: If and how well this analog option works is not verified or tested.
-
 ----
 
 ## AS5600L class
@@ -697,17 +746,23 @@ priority is relative.
   - is there improvement possible.
 
 
+
 #### Could
 
-- add error handling
 - investigate PGO programming pin.
 - check for compatible devices
   - AS5200 ?
 - investigate performance
   - basic performance per function
   - I2C improvements
   - software direction
-
+- implement extended error handling in public functions.
+  - will increase footprint !! how much?
+  - writeReg() only if readReg() is OK ==> prevent incorrect writes
+    - ```if (_error != 0) return false;```
+  - set AS5600_ERROR_PARAMETER  e.g. setZPosition()
+  - a derived class with extended error handling?
+
 
 #### Wont (unless)
 

examples/AS5600L_set_address/AS5600L_set_address.ino

@@ -2,10 +2,11 @@
 //    FILE: AS5600L_set_address.ino
 //  AUTHOR: Rob Tillaart
 // PURPOSE: demo
+//     URL: https://github.com/RobTillaart/AS5600
 
 
 #include "AS5600.h"
-#include "Wire.h"
+
 
 AS5600L ASL;   //  use default Wire
 

examples/AS5600_I2C_frequency/AS5600_I2C_frequency.ino

@@ -2,10 +2,11 @@
 //    FILE: AS5600_I2C_frequency.ino
 //  AUTHOR: Rob Tillaart
 // PURPOSE: demo
+//     URL: https://github.com/RobTillaart/AS5600
 
 
 #include "AS5600.h"
-#include "Wire.h"
+
 
 AS5600L as5600;   //  use default Wire
 

examples/AS5600_angular_speed/AS5600_angular_speed.ino

@@ -2,10 +2,11 @@
 //    FILE: AS5600_angular_speed.ino
 //  AUTHOR: Rob Tillaart
 // PURPOSE: demo
+//     URL: https://github.com/RobTillaart/AS5600
 
 
 #include "AS5600.h"
-#include "Wire.h"
+
 
 AS5600L as5600;   //  use default Wire
 
@@ -24,7 +25,7 @@ void setup()
 
   Serial.println(as5600.getAddress());
 
-  // as5600.setAddress(0x40);  // AS5600L only
+  // as5600.setAddress(0x40);  //  AS5600L only
 
   int b = as5600.isConnected();
   Serial.print("Connect: ");

examples/AS5600_angular_speed_RPM/AS5600_angular_speed_RPM.ino

@@ -2,10 +2,11 @@
 //    FILE: AS5600_angular_speed_RPM.ino
 //  AUTHOR: Rob Tillaart
 // PURPOSE: demo
+//     URL: https://github.com/RobTillaart/AS5600
 
 
 #include "AS5600.h"
-#include "Wire.h"
+
 
 AS5600 as5600;   //  use default Wire