0.9.0

- Improved documentation for `aoosp_adcled.ino`, `aoosp_adcpot.ino`,
  `aoosp_cluster.ino`, `aoosp_sync.ino`, and `aoosp_otp.ino`.
- `aoosp_exec_otpdump()` now dumps fields in table format (when passing `AOOSP_OTPDUMP_CUSTOMER_FIELDS`);
  old format retained via `AOOSP_OTPDUMP_CUSTOMER_FIELDSLIST`; updated examples and doc.
- `aoosp_exec_otpdump()` now includes the EVK fields (at address 0x1F).
- Added `aoosp_exec_skipchns_get()` and `aoosp_exec_skipchns_set()`.
- Added example `aoosp_i2c12.ino` (12 bits I2C).
- Added support for 12 bit I2C: `aoosp_send_i2cread12()`, `aoosp_send_i2cwrite12()`,
  and macros `aoosp_exec_i2cread12()`, `aoosp_exec_i2cwrite12()`.
- Improved comments in `aoosp_send.cpp/h`.
- Added link to examples.

Author: Maarten Pennings

examples/aoosp_adcled/aoosp_adcled.ino

@@ -62,9 +62,10 @@ Measured (10x) at 24mA and 100% PWM
 
 
 // Address of the SAID whose Vf we measure
-#define TARGET_ADDR    0x001  // SAID OUT on OSP32 (ALERT: make sure to select a SAID version B, not A)
+#define TARGET_ADDR    0x001  // SAID OUT on OSP32 (ALERT: make sure to select a SAID version v1.1, not v1.0)
 #define COUNT          10     // Averaging ADC over COUNT samples
 #define PWM            0xFFFF // Highest PWM gives highest accuracy (for ADC measurement)
+// See https://github.com/ams-OSRAM/OSP_aotop/tree/main/extras/manuals/saidversions
 
 
 // Simple error handling

examples/aoosp_adcpot/aoosp_adcpot.ino

@@ -32,34 +32,34 @@ RGB LED.
 
 HARDWARE
 The demo runs on the OSP32 board; connect the OUT to the IN (loop back).
-Furthermore, connect a (eg 10k) potmeter over GND and VDD (eg from J3C)
-and connect the sliding contact of the potmeter to pin S2_B1. This 
-requires removing a jumper. See photo connections.jpg in the directory 
-for this sketch. Also make sure the correct MUX input is selected, see
-#define of TARGET_DRV.
+Furthermore, connect a (e.g. 10k) potentiometer over GND and VDD 
+(e.g. from J3C) and connect the sliding contact of the potentiometer to 
+pin S2_B1. This requires removing a jumper. See photo connections.jpg in 
+the directory for this sketch. 
+Also make sure the correct MUX input is selected, see #define TARGET_ADCCHN.
 In Arduino select board "ESP32S3 Dev Module".
 
       +-------------------------+
       | OPS32                   |
   USB |                     OUT o----+
-  ----o CMD        SAID IN      |    | loopback cable
+  ----o CMD          SAIDIN     |    | loopback cable
       |                 []   IN o----+
-      | [+-]         [] [] []   |
+      | [+-]          O O O     |
       +--++-------------+-------+
-        ||             |S2_B1
-        ||            \|/
-        |+-----############--+
-        |        potmeter    |
-        +--------------------+
+         ||             |S2_B1
+         ||            \|/
+         |+----#############--+
+         |     potentiometer  |
+         +--------------------+
 
 BEHAVIOR
-When the potmeter is turned, the left RGB of SAID IN changes from red to blue.
-The Serial shows the measured (raw ADC and the) voltage. 
+When the potentiometer is turned, the left RGB of SAID IN changes from red 
+to blue. The Serial shows the measured (raw ADC and the) voltage. 
 Please note the following
 - The ADC (0..1023) has a voltage range of about 3.5V. As a result only 2/3 
-  of the potmeter range (assuming 0..5V) the values will change.
+  of the potentiometer range (assuming 0..5V) the values will change.
 - The ADC measures with respect to VDD (not GND!), therefore the measurement
-  range is rougly 1.5..5.0.
+  range is roughly 1.5..5.0.
 - When this demo is run from USB CMD, there is a voltage drop caused by
   the protection diode on the ESP32 board. This results in a VDD that is 
   below 5V (assuming an accurate USB power supply). This is "calibrated"
@@ -70,7 +70,7 @@ Welcome to aoosp_adcpot.ino
 version: result 0.4.5 spi 0.5.8 osp 0.7.0
 spi: init
 osp: init
-TARGET_DRV=6 (see #define to check if it matches your HW)
+TARGET_ADCCHN=6 (see #define to check if it matches your HW)
 ADC:430 mV:3265
 ADC:429 mV:3268
 ADC:429 mV:3268
@@ -80,16 +80,17 @@ ADC:429 mV:3268
 */
 
 
-// Address of the SAID and its ADC channel with the potmeter
+// Address of the SAID and its ADC channel with the potentiometer
 #define TARGET_ADDR    0x002 // SAID IN on OSP32
-#define TARGET_FBCHN   2     // Feedback channel of that SAID (left-most RGB of SAID IN)
-#define TARGET_DRV     6     // SAID version v1.1: 1=R0 2=R1 3=R2 4=B0 5=B1 6=B2 7=G0 8=G1 9=G2 
+#define TARGET_FBCHN   2     // LED feedback channel of that SAID (left-most RGB of SAID IN)
+#define TARGET_ADCCHN  6     // The ADC channel the potentiometer is connected to - for SAID V1.0, B1 is on channel 6, for SAID V1.1 on channel 5.
 // On the OSP32 board, pin B1 of SAID IN is available via a jumper.
-// That pin is used for the ADC, so we need to set the ADC MUX for that pin.
+// We connect the potentiometer to that pin, so the ADC MUX must activate that channel.
+// The mapping from ADC channel to driver is as follows:
+//   SAID version V1.1: 1=R0 2=R1 3=R2 4=B0 5=B1 6=B2 7=G0 8=G1 9=G2 
 // Some EVKs have older SAIDs (v1.0) for footprint "SAID IN". 
-// Those older versions differ differ in ADC MUX numbering.
-// In SAID version V1.0, B1 is connected to MUX 6.
-// In SAID version V1.1, B1 is connected to MUX 5.
+// Those older versions differ in ADC MUX numbering.
+//   SAID version V1.0: 1=R0 2=G0 3=B0 4=R1 5=G1 6=B1 7=R2 8=G2 9=B2
 // See https://github.com/ams-OSRAM/OSP_aotop/tree/main/extras/manuals/saidversions
 
 
@@ -104,18 +105,18 @@ void setup() {
 
   aospi_init();
   aoosp_init();
-  Serial.printf("TARGET_DRV=%d (see #define to check if it matches your HW)\n",TARGET_DRV);
+  Serial.printf("TARGET_ADCCHN=%d (see #define to check if it matches your HW)\n",TARGET_ADCCHN);
 
   // Bring up chain
   aoresult_t result;
-  result= aoosp_exec_resetinit(); CHECKRESULT("aoosp_exec_resetinit");
+  result= aoosp_exec_resetinit(); CHECKRESULT("resetinit");
   if( aoosp_exec_resetinit_last()!=2 ) { Serial.printf("ERROR: demo is written for OSP32 with loop back cable\n"); return; }
   result= aoosp_send_clrerror(0x000); CHECKRESULT("clrerror");
   result= aoosp_send_goactive(0x000); CHECKRESULT("goactive");
 
-  // Measurements _not_ synchronized with PWM (because external pot); ADC mapped to TARGET_DRV.
+  // Measurements _not_ synchronized with PWM (because external pot); ADC mapped to TARGET_ADCCHN.
   // See documentation of `aoosp_send_setadc()` for details on the ADC behavior.
-  result= aoosp_send_setadc(TARGET_ADDR, AOOSP_ADC_FLAGS_SYNC_DIS+TARGET_DRV ); CHECKRESULT("setadc");
+  result= aoosp_send_setadc(TARGET_ADDR, AOOSP_ADC_FLAGS_SYNC_DIS+TARGET_ADCCHN ); CHECKRESULT("setadc");
   // ADC measurement takes 730us, wait that before first readadcdat.
   delay(1); 
 }

examples/aoosp_cluster/aoosp_cluster.ino

@@ -1,6 +1,6 @@
 // aoosp_cluster.ino - illustrates how to use driver cluster 
 /*****************************************************************************
- * Copyright 2024 by ams OSRAM AG                                            *
+ * Copyright 2024,2025 by ams OSRAM AG                                       *
  * All rights are reserved.                                                  *
  *                                                                           *
  * IMPORTANT - PLEASE READ CAREFULLY BEFORE COPYING, INSTALLING OR USING     *
@@ -310,19 +310,19 @@ void set_cluster(int newcluster) {
 
   // Print old cluster configuration
   result= aoosp_send_readotp(ADDR, OTPADDR_CH_CLUSTERING, &val, 1); cluster = val >> 5;
-  if( result!=aoresult_ok ) Serial.printf("aoosp_send_readotp %s\n", aoresult_to_str(result) );
+  if( result!=aoresult_ok ) Serial.printf("readotp %s\n", aoresult_to_str(result) );
   Serial.printf("From OTP[%02X]=%02X: cluster=%d\n",OTPADDR_CH_CLUSTERING, val, cluster);
 
   // Check test password
   if( aoosp_said_testpw_get()==AOOSP_SAID_TESTPW_UNKNOWN ) Serial.printf("ERROR: SAID test password not configured\n" );
 
   // Write new cluster to OTP (mirror)
   result= aoosp_exec_setotp(ADDR, OTPADDR_CH_CLUSTERING, OTPMASK_CLUSTER(newcluster), OTPMASK_CH_CLUSTERING); 
-  if( result!=aoresult_ok ) Serial.printf("setpwmchn %s\n", aoresult_to_str(result) );
+  if( result!=aoresult_ok ) Serial.printf("setotp %s\n", aoresult_to_str(result) );
 
   // Print old cluster configuration
   result= aoosp_send_readotp(ADDR, OTPADDR_CH_CLUSTERING, &val, 1); cluster = val >> 5;
-  if( result!=aoresult_ok ) Serial.printf("aoosp_send_readotp %s\n", aoresult_to_str(result) );
+  if( result!=aoresult_ok ) Serial.printf("readotp %s\n", aoresult_to_str(result) );
   Serial.printf("To   OTP[%02X]=%02X: cluster=%d\n",OTPADDR_CH_CLUSTERING, val, cluster);
 }
 
@@ -331,13 +331,13 @@ void cluster_demo() {
   aoresult_t result;
   uint32_t   id;
 
-  // Reset and initialize all nodes and
+  // Reset and initialize all nodes
   result= aoosp_exec_resetinit(); 
-  if( result!=aoresult_ok ) Serial.printf("setpwmchn %s\n", aoresult_to_str(result) );
+  if( result!=aoresult_ok ) Serial.printf("resetinit %s\n", aoresult_to_str(result) );
 
   // Check node ADDR is a SAID
   result= aoosp_send_identify(ADDR, &id);
-  if( result!=aoresult_ok ) Serial.printf("setpwmchn %s\n", aoresult_to_str(result) );
+  if( result!=aoresult_ok ) Serial.printf("identify %s\n", aoresult_to_str(result) );
   if( ! AOOSP_IDENTIFY_IS_SAID(id) ) Serial.printf("ERROR: targeting node %03X, but this is not a SAID\n", ADDR );
 
   // Configure cluster 
@@ -346,11 +346,11 @@ void cluster_demo() {
 
   // Clear the error flags of all nodes; SAIDs have the V flag (over-voltage) after reset, preventing them from going active.
   result= aoosp_send_clrerror(0x000); 
-  if( result!=aoresult_ok ) Serial.printf("setpwmchn %s\n", aoresult_to_str(result) );
+  if( result!=aoresult_ok ) Serial.printf("clrerror %s\n", aoresult_to_str(result) );
 
   // Switch the state of all nodes to active (allowing to switch on LEDs).
   result= aoosp_send_goactive(0x000); 
-  if( result!=aoresult_ok ) Serial.printf("setpwmchn %s\n", aoresult_to_str(result) );
+  if( result!=aoresult_ok ) Serial.printf("goactive %s\n", aoresult_to_str(result) );
 
   // Run all 9 cases of switching one driver on
   Serial.printf("\n");