add error handling

AS5600.cpp

@@ -1,7 +1,7 @@
 //
 //    FILE: AS56000.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.5.1
+// VERSION: 0.5.2
 // 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.5.2
 // 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.5.2"))
+
 
 //  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,17 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.5.2] - 2024-01-25
+- add experimental error handling
+- 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

@@ -439,6 +439,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
@@ -613,6 +647,7 @@ This output could be used to connect multiple sensors to different analogue port
 
 **Warning**: If and how well this analog option works is not verified or tested.
 
+
 ----
 
 ## AS5600L class
@@ -697,17 +732,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
 

examples/AS5600_burn_conf_mang/AS5600_burn_conf_mang.ino

@@ -2,8 +2,8 @@
 //    FILE: AS5600_burn_conf_mang.ino
 //  AUTHOR: Rob Tillaart
 // PURPOSE: demo (not tested yet - see issue #38)
-
-
+//     URL: https://github.com/RobTillaart/AS5600
+//
 //  WARNING
 //  As burning the settings can only be done once this sketch has to be used with care.
 //
@@ -17,7 +17,6 @@
 
 #include "AS5600.h"
 
-#include "Wire.h"
 
 AS5600 as5600;   //  use default Wire
 //  AS5600L as5600;

examples/AS5600_burn_zpos/AS5600_burn_zpos.ino

@@ -2,8 +2,8 @@
 //    FILE: AS5600_burn_zpos.ino
 //  AUTHOR: Rob Tillaart
 // PURPOSE: demo (not tested yet - see issue #38)
-
-
+//     URL: https://github.com/RobTillaart/AS5600
+//
 //  WARNING
 //  As burning the angle can only be done three times this sketch has to be used with care.
 //
@@ -17,7 +17,6 @@
 
 #include "AS5600.h"
 
-#include "Wire.h"
 
 AS5600 as5600;   //  use default Wire
 //  AS5600L as5600;

examples/AS5600_demo/AS5600_demo.ino

@@ -2,10 +2,11 @@
 //    FILE: AS5600_demo.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_demo_ESP32/AS5600_demo_ESP32.ino

@@ -2,10 +2,11 @@
 //    FILE: AS5600_demo.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_demo_RP2040/AS5600_demo_RP2040.ino

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