0.3.1

- Typos fixed in `aoosp_send.cpp`.
- In `aoosp_send.h` cleaned up `AOOSP_ADDR_xxx`.
- Typos fixed in `readme.md`, `aoosp.cpp`, `aoosp_crc.cpp`, `aoosp_exec.h`.
- Typos fixed in `aoosp_i2c.ino`, `aoosp_sync.ino`, `aoosp_topo.ino`.
- Typos fixed in `aoosp_exec.cpp`.

Author: maarten-pennings

examples/aoosp_i2c/aoosp_i2c.ino

@@ -25,7 +25,7 @@
 /*
 DESCRIPTION
 This demo first performs an I2C scan using the I2C bridge in a SAID.
-Then it issues I2C read and write transactions to an EEPROM memory.
+Then it issues I2C read and write transactions to an EEPROM memory,
 assumed to have I2C device address 0x50 connected to the first SAID.
 Finally it polls the INT line and shows its status on SAID1.RGB0.
 

examples/aoosp_otp/aoosp_otp.ino

@@ -24,7 +24,8 @@
 
 /*
 DESCRIPTION
-This demo reads and writes from/to the OTP of a SAID.
+This demo reads and writes from/to the OTP (one time programmable memory)
+of a SAID.
 Note that this accesses the OTP mirror in RAM, not the actual OTP ("ROM").
 The mirror is persistent over RESET, but not over POR (power on reset).
 The latter requires the CUST, BURN, IDLE steps, which are beyond the scope 

examples/aoosp_sync/aoosp_sync.ino

@@ -33,7 +33,7 @@ PWM settings.
 
 Instead of sending a SYNC telegram, there is also the option to use the
 SYNC pin of the SAID (pin B1). To demonstrate that, define USE_HARDWARE_SYNC
-and on the OSP32 board have jummper J8 connect SAID2.B2 to the ESP32 GPIO9
+and on the OSP32 board have jumper J8 connect SAID2.B2 to the ESP32 GPIO9
 (instead of LED L2.1_B). Only SAID2 is wired for hardware sync on OSP32.
 
 HARDWARE

examples/aoosp_topo/aoosp_topo.ino

@@ -25,7 +25,7 @@
 /*
 DESCRIPTION
 This demo scans all nodes and prints out the chain configuration:
-comms for both SIOs, dir, state, number of RGBs and I2C.
+comms for both SIOs, direction, power state, number of RGBs and I2Cs.
 
 HARDWARE
 The demo should run on the OSP32 board. Either have a terminator in the 

library.properties

@@ -1,5 +1,5 @@
 name=OSP Telegrams aoosp
-version=0.3.0
+version=0.3.1
 author=ams-OSRAM
 maintainer=ams-OSRAM
 sentence=A library that constructs OSP telegrams to send, and destructs received OSP telegrams.

readme.md

@@ -14,10 +14,11 @@ Library _aoosp_ is at the heart of the dependency graph.
 
 It contains functions to construct telegrams (byte arrays) to be send to OSP nodes.
 It also contains functions to destruct response telegrams received back from OSP nodes.
-Both functions are hidden behind the API; the API allows sending and receiving telegrams.
+Both functions are hidden behind the API; the API allows sending and receiving telegrams,
+which involves constructing, transmit-out, transmit-in and destructing.
 
-For telegram transmit this library relies on a communications layer, typically _aospi_.
-That library expects a board like **OSP32**.
+For telegram transmission this library relies on a communications layer, typically _aospi_.
+That library expects a board like the **OSP32** board in the evaluation kit.
 
 ![aoosp in context](extras/aolibs-aoosp.drawio.png)
 
@@ -40,7 +41,7 @@ File > Examples > OSP Telegrams aoosp > ...
 
 - **aoosp_topo**   
   This demo scans all nodes and prints out the chain configuration:
-  comms for both SIOs, dir, state, number of RGBs and I2C.
+  comms for both SIOs, direction, power state, number of RGBs and I2Cs.
 
 - **aoosp_error**  
   This demo shows how error handling works in SAID. The STAT register has 
@@ -56,22 +57,23 @@ File > Examples > OSP Telegrams aoosp > ...
 
 - **aoosp_i2c**   
   This demo first performs an I2C scan using the I2C bridge in a SAID.
-  Then it issues I2C read and write transactions to an EEPROM memory.
+  Then it issues I2C read and write transactions to an EEPROM memory,
   assumed to have I2C device address 0x50 connected to the first SAID.
   Finally it polls the INT line and shows its status on SAID1.RGB0.
 
 - **aoosp_otp**   
-  This demo reads and writes from/to the OTP of a SAID.
+  This demo reads and writes from/to the OTP (one time programmable 
+  memory) of a SAID.
 
 - **aoosp-sync**  
   This demo shows how to use the SYNC feature; a feature that switches on all 
   LEDs at the same time. We first enable (channels) of nodes for SYNC
   (AOOSP_CURCHN_FLAGS_SYNCEN). Next, set those channels to some PWM value.
   Finally we issue a SYNC by broadcasting the SYNC telegram. This makes
   all (channels) of all nodes that are configured for SYNC to activate their
-  PWM settings.
+  PWM settings. It is also possible to pulse a pin as hardware SYNC.
 
-- **aoosp_time**
+- **aoosp_time**  
   This demo sends a series of telegrams. The series originally comes from 
   `aomw_topo_build`. We measure how long it takes to run that series.
   Once we use the high level aoosp API, and once we use low level aospi API.
@@ -89,10 +91,10 @@ This library contains 4 modules, see figure below (arrows indicate #include).
 
 - **aoosp_prt** (`aoosp_prt.cpp` and `aoosp_prt.h`) is a slightly bigger module that implements 
   several functions to pretty print telegrams. It is normally not used in production code.
-  It is extensively used by the logging feature of module aoosp_send.
+  It is extensively used by the logging feature of module `aoosp_send`.
 
 - **aoosp_send** (`aoosp_send.cpp` and `aoosp_send.h`) is the _core_ module of the library.
-  It contains functions the send commands and receive the responses if there is any.
+  It contains functions that send commands and receive the responses if there is any.
   The module supports both RGBi's and SAIDs. Not all telegrams are implemented yet.
   The module is stateless, with one exception: it records if logging is enabled or disabled.
 
@@ -117,7 +119,7 @@ The headers contain little documentation; for that see the module source files.
 
 ### aoosp
 
-- `aoosp_init()` not really needed, but added for forward compatibility.
+- `aoosp_init()` not really needed (aoosp has no state to init), but added for forward compatibility.
 - `AOOSP_VERSION`  identifies the version of the library.
 
 
@@ -131,16 +133,18 @@ The headers contain little documentation; for that see the module source files.
 Contains several functions to print telegram fields more user friendly. Examples are:
 
 - `aoosp_prt_temp_said()` to convert a SAID raw temperature to Celsius.
-- `aoosp_prt_stat_state()` to convert a node state to a string.
+- `aoosp_prt_stat_state()` to convert a node stat to a string describing the power state.
 - `aoosp_prt_bytes()` to convert a byte array (like a telegram) to a string.
+- ...
 
 These functions are publicly accessible, but are intended for logging in this library.
 
 Warning: pretty print functions that return a `char *` all use the same global 
 character buffer  for returning the string. This means that only _one_ such function 
-can be used at a time. For example this will not work: 
+can be used at a time. For example this will _not_ work:
+ 
 ```
-  printf("%s-%s", aoosp_prt_stat_rgbi(x), aoosp_prt_stat_said(x) )
+  printf("%s-%s", aoosp_prt_stat_rgbi(x), aoosp_prt_stat_said(x) ); // ERROR: double prt
 ```
 
 
@@ -152,11 +156,12 @@ Examples are
 - `aoosp_send_reset()` resets all nodes in the chain (all "off"; they also lose their address).
 - `aoosp_send_initloop()` assigns an address to each node; also configures all nodes for Loop.
 - `aoosp_send_clrerror()` clears the error flags of the addressed node.
-- `aoosp_send_goactive()` switches the state of the addressed node to active.
-- `aoosp_send_readpwmchn()`  asks the addressed node to respond with its PWM settings of one of its channel.
+- `aoosp_send_goactive()` switches the power state of the addressed node to active ("on").
+- `aoosp_send_setpwmchn()` configures the PWM settings of one channel of the addressed node ("lit").
+- ...
 
 This module supports logging. 
-Via `aoosp_loglevel_set()` and `aoosp_loglevel_get()` the log level can be manipulated:
+Via `aoosp_loglevel_set()` and `aoosp_loglevel_get()` the log level can be managed:
 
 - `aoosp_loglevel_none` nothing is logged (default).
 - `aoosp_loglevel_args` logging of sent and received telegram arguments.
@@ -169,8 +174,8 @@ Some operations on OSP nodes require multiple telegrams.
 Some frequent ones have been abstracted in this module.
 
 - `aoosp_exec_resetinit()`         sends RESET and INIT telegrams, auto detecting BiDir or Loop.
-- `aoosp_exec_otpdump()`           reads the entire OTP and prints details requested in flags.
-- `aoosp_exec_setotp()`            updates one bye in OTP.
+- `aoosp_exec_otpdump()`           reads the entire OTP (mirror) and prints details requested in flags.
+- `aoosp_exec_setotp()`            updates one byte in the OTP (mirror).
 - `aoosp_exec_i2cenable_get()`     reads the I2C_BRIDGE_EN bit in OTP (mirror).
 - `aoosp_exec_i2cenable_set()`     writes the I2C_BRIDGE_EN bit in OTP (mirror).
 - `aoosp_exec_i2cpower()`          checks if the SAID has an I2C bridge, if so, powers the I2C bus.
@@ -182,9 +187,16 @@ Some frequent ones have been abstracted in this module.
 
 ## Version history _aoosp_
 
+- **2024 aug 9, 0.3.1**
+  - Typos fixed in `aoosp_send.cpp`.
+  - In `aoosp_send.h` cleaned up `AOOSP_ADDR_xxx`.
+  - Typos fixed in `readme.md`, `aoosp.cpp`, `aoosp_crc.cpp`, `aoosp_exec.h`.
+  - Typos fixed in `aoosp_i2c.ino`, `aoosp_sync.ino`, `aoosp_topo.ino`.
+  - Typos fixed in `aoosp_exec.cpp`.
+  
 - **2024 August 5, 0.3.0**  
-  - In `aoosp_send.h` all non-implemented TID tagged as not-yet-implemented or reserved.
-  - Corrected link to GitHub from aotop to OSP_aotop.
+  - In `aoosp_send.h` all non-implemented TIDs tagged as not-yet-implemented or reserved.
+  - Corrected link to GitHub from aotop to `OSP_aotop`.
   - Remove "oalib" from `sentence=` in `library.properties`.
   - Added `#include "../../said-password.h"`.
   - Added `aoosp_exec_syncpinenable_get()` and `aoosp_exec_syncpinenable_set()` and hw sync in `aoosp_sync.ino`.

src/aoosp.cpp

@@ -26,10 +26,10 @@
 
 /*!
     @brief  Initializes the aoosp library.
-    @note   At this moment, the aoosp lib has no state to (initialize).
-            Present for future extensions that do need initialization
+    @note   At this moment, the aoosp lib has no state (to initialize).
+            Present for future extensions that do need initialization.
 */
 void aoosp_init() {
-  // No init is needed, but placed for future extensions.
+  // No init is needed, but already present for future extensions.
   Serial.printf("osp: init\n");
 }

src/aoosp.h

@@ -23,7 +23,7 @@
 
 
 // Identifies lib version
-#define AOOSP_VERSION "0.3.0"
+#define AOOSP_VERSION "0.3.1"
 
 
 // Include the (headers of the) modules of this app

src/aoosp_crc.cpp

@@ -24,7 +24,7 @@
 
 
 /*!
-    @brief  Computes the OSP CRC for a sequence of bytes
+    @brief  Computes the OSP CRC for a sequence of bytes.
     @param  buf
             A pointer to a sequence of bytes.
     @param  size

src/aoosp_exec.cpp

@@ -66,7 +66,7 @@ aoresult_t aoosp_exec_resetinit(uint16_t *last, int *loop) {
 
   // Try INITLOOP (recall to set mux)
   aospi_dirmux_set_loop();
-  result= aoosp_send_initloop(1,&last2,&temp,&stat);
+  result= aoosp_send_initloop(0x001,&last2,&temp,&stat);
   if( result==aoresult_ok ) {
     *last=last2;  
     *loop=1; 
@@ -81,7 +81,7 @@ aoresult_t aoosp_exec_resetinit(uint16_t *last, int *loop) {
 
   // Try INITBIDIR (recall to set mux)
   aospi_dirmux_set_bidir(); 
-  result= aoosp_send_initbidir(1,&last2,&temp,&stat);
+  result= aoosp_send_initbidir(0x001,&last2,&temp,&stat);
   if( result==aoresult_ok ) {
     *last=last2;  
     *loop=0; 
@@ -165,11 +165,11 @@ aoresult_t aoosp_exec_otpdump(uint16_t addr, int flags) {
 
 
 /*!
-    @brief  Reads the OTP (mirror) updates location otpaddr
+    @brief  Reads the OTP (mirror) and updates location otpaddr
             by and-ing it with `andmask` then or-ing it with `ormask`,
             then writing the value back to the OTP (mirror).
     @param  addr
-            The address to send the telegram to
+            The address to send the telegram to (unicast).
             (theoretically, use 0 for broadcast, or 3F0..3FE for group).
     @param  otpaddr
             The address of the OTP memory.
@@ -225,7 +225,7 @@ aoresult_t aoosp_exec_setotp(uint16_t addr, uint8_t otpaddr, uint8_t ormask, uin
 /*!
     @brief  Reads the I2C_BRIDGE_EN bit from OTP (mirror).
     @param  addr
-            The address to send the telegram to
+            The address to send the telegram to (unicast).
             (theoretically, use 0 for broadcast, or 3F0..3FE for group).
     @param  enable
             Output parameter returning the value of I2C_BRIDGE_EN.
@@ -241,16 +241,17 @@ aoresult_t aoosp_exec_i2cenable_get(uint16_t addr, int * enable) {
   // Read current OTP row
   uint8_t buf[8];
   aoresult_t result = aoosp_send_readotp(addr,otp_addr,buf,8);
+  if( result!=aoresult_ok ) return result;
   // Check the OTP bit
   *enable = (buf[0] & otp_bit) != 0;
-  return result;
+  return aoresult_ok;
 }
 
 
 /*!
     @brief  Writes the I2C_BRIDGE_EN bit to OTP (mirror).
     @param  addr
-            The address to send the telegram to
+            The address to send the telegram to (unicast).
             (theoretically, use 0 for broadcast, or 3F0..3FE for group).
     @param  enable
             The new value for I2C_BRIDGE_EN.
@@ -279,7 +280,7 @@ aoresult_t aoosp_exec_i2cenable_set(uint16_t addr, int enable) {
     @brief  Checks the address SAID if its OTP has the I2C bridge feature 
             enabled, if so, powers the I2C bus.
     @param  addr
-            The address to send the telegram to
+            The address to send the telegram to (unicast).
             (theoretically, use 0 for broadcast, or 3F0..3FE for group).
     @return aoresult_ok if all ok, otherwise an error code.
 */
@@ -302,7 +303,7 @@ aoresult_t aoosp_exec_i2cpower(uint16_t addr) {
 /*!
     @brief  Reads the SYNC_PIN_EN bit from OTP (mirror).
     @param  addr
-            The address to send the telegram to
+            The address to send the telegram to (unicast).
             (theoretically, use 0 for broadcast, or 3F0..3FE for group).
     @param  enable
             Output parameter returning the value of SYNC_PIN_EN.
@@ -317,16 +318,17 @@ aoresult_t aoosp_exec_syncpinenable_get(uint16_t addr, int * enable) {
   // Read current OTP row
   uint8_t buf[8];
   aoresult_t result = aoosp_send_readotp(addr,otp_addr,buf,8);
+  if( result!=aoresult_ok ) return result;
   // Check the OTP bit
   *enable = (buf[0] & otp_bit) != 0;
-  return result;
+  return aoresult_ok;
 }
 
 
 /*!
     @brief  Writes the SYNC_PIN_EN bit to OTP (mirror).
     @param  addr
-            The address to send the telegram to
+            The address to send the telegram to (unicast).
             (theoretically, use 0 for broadcast, or 3F0..3FE for group).
     @param  enable
             The new value for SYNC_PIN_EN.
@@ -352,10 +354,10 @@ aoresult_t aoosp_exec_syncpinenable_set(uint16_t addr, int enable) {
 
 
 /*!
-    @brief  Writes count bytes from buf, into register raddr in I2C device 
-            daddr7, attached to OSP node addr.
+    @brief  Writes `count` bytes from `buf`, into register `raddr` in I2C 
+            device `daddr7`, attached to OSP node `addr`.
     @param  addr
-            The address to send the telegram to.
+            The address to send the telegram to (unicast).
             (theoretically, use 0 for broadcast, or 3F0..3FE for group).
     @param  daddr7
             The 7 bits I2C device address used in mastering the write.
@@ -393,8 +395,8 @@ aoresult_t aoosp_exec_i2cwrite8(uint16_t addr, uint8_t daddr7, uint8_t raddr, co
 
 
 /*!
-    @brief  Reads count bytes into buf, from register raddr in I2C device 
-            daddr7, attached to OSP node addr.
+    @brief  Reads `count` bytes into `buf`, from register `raddr` in I2C 
+            device `daddr7`, attached to OSP node `addr`.
     @param  addr
             The address to send the telegram to (unicast).
     @param  daddr7
@@ -433,5 +435,3 @@ aoresult_t aoosp_exec_i2cread8(uint16_t addr, uint8_t daddr7, uint8_t raddr, uin
   result = aoosp_send_readlast(addr,buf,count);
   return result;
 }
-
-