0.5.7

- Added example `aospi_bringup.ino`.
- Text correction in `readme.md`; added _level shifter pull-ups issue_.

Author: Maarten Pennings

examples/aospi_bringup/aospi_bringup.ino

@@ -0,0 +1,57 @@
+// aospi_bringup.ino - test if communication between MCU and OSP node is operational
+/*****************************************************************************
+ * Copyright 2024 by ams OSRAM AG                                            *
+ * All rights are reserved.                                                  *
+ *                                                                           *
+ * IMPORTANT - PLEASE READ CAREFULLY BEFORE COPYING, INSTALLING OR USING     *
+ * THE SOFTWARE.                                                             *
+ *                                                                           *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS       *
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT         *
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS         *
+ * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT  *
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,     *
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT          *
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,     *
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY     *
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT       *
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE     *
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.      *
+ *****************************************************************************/
+#include <aospi.h>
+
+
+/*
+DESCRIPTION
+This sketch just sends a RESET telegram to a node. We check whether that 
+node forwards the telegram. The checking is done using a logic analyzer. 
+A next step is sending INITBIDIR.
+
+HARDWARE
+The demo runs on the OSP32 board. Add a pull-ups on SION and SIOP of OUT, 
+and connect a logic analyzer them.
+In Arduino select board "ESP32S3 Dev Module".
+
+BEHAVIOR
+See readme.md for how to capture and analyze the telegrams.
+
+OUTPUT
+Nothing printed to Serial; check the logic analyzer.
+*/
+
+
+const uint8_t reset[]     = {0xA0, 0x00, 0x00, 0x22}; // RESET(000)
+const uint8_t initbidir[] = {0xA0, 0x04, 0x02, 0xA9}; // INITBIDIR(001)
+
+
+void setup() {
+  aospi_init();
+}
+
+
+void loop() {
+  aospi_tx( reset, sizeof reset );
+  delayMicroseconds(150); 
+  aospi_tx( initbidir, sizeof initbidir );
+  delay(1000);
+}

examples/aospi_bringup/extras/hardware.jpg

@@ -0,0 +1,137 @@
+# Bring-up
+
+This project helps checking if an MCU communicates with an OSP node.
+
+
+## Introduction
+
+When bringing up an OSP based system, the first hurdle is to get communication
+established, most notably between the MCU and the first node. The obvious
+way to detect successful communication is to switch on an LED of the node.
+
+However, this requires not only successful communication, but also a correct
+sequence of telegrams (assign address, clear errors, switch to active state,
+set drive current, set PWM value).
+
+In this sketch we just send a RESET telegram to one node, and check whether
+that node forwards it. 
+
+An optional next step is sending INITBIDIR. Remember that a node needs 
+150 μs for executing a RESET; a delay for that needs to precede the 
+INITBIDIR telegram.
+
+
+## Hardware
+
+The demo runs on the OSP32 board. We cut a MiniBridge cable in two, plug it
+in OUT, add a pull-up on SION and SIOP, and connect a logic analyzer.
+An alternative is to use the OUT pin header to solder a header or even
+directly pull-ups. Recommended pull-up value is 10kΩ.
+
+![hardware setup](extras/hardware.jpg)
+
+The two pull-ups configure the port for USE mode (aka CAN mode).
+Unlike the standard LVDS mode, this uses voltage levels to communicate,
+so easier to capture using a logic analyzer.
+
+
+## Logic analyzer
+
+We used a [Saleae](https://www.saleae.com/) logic analyzer.
+It even has a slicer for Manchester. These are the settings for the slicer.
+
+![Slicer settings](extras/slicer.png)
+
+
+## Software
+
+Run the `aospi_bringup.ino` sketch (compile for "ESP32S3 Dev Module" and upload).
+It will send a RESET and INITBIDIR every second. Arm the Saleae for a capture
+to create a trace. The resulting [trace](extras/trace.sal) has two telegrams,
+one for RESET, one for INITBIDIR.
+
+
+## RESET trace
+
+The first trace captures the RESET telegram.
+
+![reset trace](extras/reset.png)
+
+The MCU sends `A0 00 00 22` to SIO1 of the node, and we see that the
+node indeed forwards the same bytes to the (non-existent) next node.
+We can use `OSP_aospi\python\telegram` to draw the telegram.
+
+```
+(env) OSP_aospi\python\telegram>run A0 00 00 22
+          +---------------+---------------+---------------+---------------+
+byteval   |      A0       |      00       |      00       |      22       |
+byteix    |0 0 0 0 0 0 0 0|1 1 1 1 1 1 1 1|2 2 2 2 2 2 2 2|3 3 3 3 3 3 3 3|
+bitix     |7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|
+bitval    |1 0 1 0 0 0 0 0|0 0 0 0 0 0 0 0|0 0 0 0 0 0 0 0|0 0 1 0 0 0 1 0|
+          +-------+-------+-----------+---+-+-------------+---------------+
+field     |preambl|      address      | psi |   command   |      crc      |
+bin       | 1010  |    0000000000     | 000 |   0000000   |   00100010    |
+hex       |  0xA  |       0x000       | 0x0 |    0x00     |   0x22 (ok)   |
+meaning   |   -   |     broadcast     |  0  |    reset    |    34 (ok)    |
+          +-------+-------------------+-----+-------------+---------------+
+```
+
+This proves that the node is operational: it receives a telegram from the MCU
+and processes it (forwards it).
+
+
+## INITBIDE trace
+
+Even more convincing is the trace of the INITBIDIR.
+The MCU sends `A0 04 02 A9` to SIO1, this means INITBIDIR(001),
+i.e. init and assign yourself address 001
+
+```
+(env) OSP_aospi\python\telegram>run A0 04 02 A9
+          +---------------+---------------+---------------+---------------+
+byteval   |      A0       |      04       |      02       |      A9       |
+byteix    |0 0 0 0 0 0 0 0|1 1 1 1 1 1 1 1|2 2 2 2 2 2 2 2|3 3 3 3 3 3 3 3|
+bitix     |7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|
+bitval    |1 0 1 0 0 0 0 0|0 0 0 0 0 1 0 0|0 0 0 0 0 0 1 0|1 0 1 0 1 0 0 1|
+          +-------+-------+-----------+---+-+-------------+---------------+
+field     |preambl|      address      | psi |   command   |      crc      |
+bin       | 1010  |    0000000001     | 000 |   0000010   |   10101001    |
+hex       |  0xA  |       0x001       | 0x0 |    0x02     |   0xA9 (ok)   |
+meaning   |   -   |    unicast(1)     |  0  |  initbidir  |   169 (ok)    |
+          +-------+-------------------+-----+-------------+---------------+
+```
+
+The outgoing telegram is different.
+
+![reset trace](extras/initbidir.png)
+
+We see the bytes `A0 08 02 F9`; when we plot that we get the following diagram.
+
+```
+(env) OSP_aospi\python\telegram>run A0 08 02 F9
+          +---------------+---------------+---------------+---------------+
+byteval   |      A0       |      08       |      02       |      F9       |
+byteix    |0 0 0 0 0 0 0 0|1 1 1 1 1 1 1 1|2 2 2 2 2 2 2 2|3 3 3 3 3 3 3 3|
+bitix     |7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|
+bitval    |1 0 1 0 0 0 0 0|0 0 0 0 1 0 0 0|0 0 0 0 0 0 1 0|1 1 1 1 1 0 0 1|
+          +-------+-------+-----------+---+-+-------------+---------------+
+field     |preambl|      address      | psi |   command   |      crc      |
+bin       | 1010  |    0000000010     | 000 |   0000010   |   11111001    |
+hex       |  0xA  |       0x002       | 0x0 |    0x02     |   0xF9 (ok)   |
+meaning   |   -   |    unicast(2)     |  0  |  initbidir  |   249 (ok)    |
+          +-------+-------------------+-----+-------------+---------------+
+```
+
+Note that the outgoing telegram is INITBIDIR(002), so we see that the
+node has actively transformed the incoming telegram: stepped the address,
+and recomputed the checksum.
+
+This means we have successful MCU-SAID communication.
+
+
+## Afterthought
+
+There are many things that can go wrong. See this libraries readme for a list
+of [issues](https://github.com/ams-OSRAM/OSP_aospi?tab=readme-ov-file#issues).
+
+(end)

examples/aospi_bringup/extras/initbidir.png

@@ -1,5 +1,5 @@
 name=OSP 2wireSPI aospi
-version=0.5.6
+version=0.5.7
 author=ams-OSRAM
 maintainer=ams-OSRAM
 sentence=A library that implements 2-wire SPI towards and from OSP nodes.

examples/aospi_bringup/extras/reset.png

@@ -96,6 +96,13 @@ File > Examples > OSP 2wireSPI aospi > ...
   (adding the fast forwarding time for each intermediate node).
   The second aspect is the impact of longer telegrams.
 
+- **aospi_bringup** ([source](examples/aospi_bringup))  
+  This sketch just sends a RESET telegram to a node. We check whether that 
+  node forwards the telegram. The checking is done using a logic analyzer. 
+  A next step is sending INITBIDIR. It is an example of how to bring-up
+  new hardware/software. There is a more detailed [readme.md](readme.md) to
+  explain the process.
+
 
 ## API
 
@@ -126,7 +133,7 @@ Here is a quick overview:
   `aospi_txrx_hops(...)` returns an estimate of the number of hops (telegram 
   forwards by intermediate nodes) that were needed by the last `aospi_txrx()`.
 
-- To testing the (OSP32) PCB the following functions are provided. The first pair
+- To test the (OSP32) PCB the following functions are provided. The first pair
   `aospi_outoena_set(...)`/`aospi_outoena_get()` allows testing the control line of 
   the output enable of the outgoing level shifter, the second pair 
   `aospi_inoena_set(...)`/`aospi_inoena_get()` allows testing the control line of 
@@ -223,6 +230,7 @@ Some issues controlling OSP nodes deserve above normal attention.
 They are discussed in various sections of this document.
 
 - RESET issue
+- level shifter pull-ups issue
 - missing SSEL issue
 - dual master issue
 - different modes issue
@@ -266,12 +274,18 @@ SAID, dedicated to sending. This level shifter has several roles.
 The level shifter used on the OSP32 board is unidirectional, 
 but that is not very relevant.
 
-If the MCU has 5V SPI lines, a level shifter is not needed. However, the 
-second (dual masters) and third bullet (_RESET issue_) still need to be 
+If the MCU has 5V SPI lines, level shifting is not needed. However, the 
+second (_dual masters_) and third bullet (_RESET issue_) still need to be 
 covered. Both could be covered with a buffer. Another option is to 
 reconfigure the MCU pins after an SPI transaction, switching them to 
 tri-state.
 
+**Warning:** some level shifters have internal pull-ups. This leads to 
+a problem related to the _RESET issue_, the _level shifter pull-ups issue_.
+If the level shifter has internal pull-ups on the lines that connect to
+the SIO port, then, after a power on, the port will be configured for 
+CAN mode, effectively blocking the node from receiving any message.
+
 
 ### Two level shifters for receiving
 
@@ -320,7 +334,7 @@ the MOSI and SCLK line as inputs is sufficient).
 ### No level shifters - 5V MCU
 
 When the MCU is 5V, there is no reason to have level shifters.
-However, the RESET issue and  dual master issue still need to be solved.
+However, the _RESET issue_ and  _dual master issue_ still need to be solved.
 This could be solved by replacing the OUT level shifter by an external buffer 
 with tri-state output. If that one is controlled via the OENA line, there is 
 no need to change the library. The IN (either from BiDir or Loop) is 5V 
@@ -348,7 +362,7 @@ The left-most column assumes a 3V3 MCU, and thus uses level shifters.
 The three architectures in this column are supported by the aospi lib.
 
 The center column assume a 5V MCU, so no level shifters are needed.
-However due to the RESET issue and dual master issue, a buffer with tri-state 
+However due to the _RESET issue_ and _dual master issue_, a buffer with tri-state 
 is needed. For BiDir and Loop only rows, no mux is needed, so the IN buffers 
 can be avoided in the lower two rows. The three architectures in the center 
 column are supported by the aospi lib.
@@ -681,6 +695,10 @@ The figure below shows details of the INITLOOP command and response.
 
 ## Version history _aospi_
 
+- **2024 November 29, 0.5.7**
+  - Added example `aospi_bringup.ino`.
+  - Text correction in `readme.md`; added _level shifter pull-ups issue_.
+
 - **2024 October 22, 0.5.6**
   - Telegram dissector (`python\telegram`) now shows casting mode.
   - Replaced clock tapping mechanism in `aospi.cpp`; from ISR to polling (faster).
@@ -729,7 +747,7 @@ The figure below shows details of the INITLOOP command and response.
 - **2024 July 7, 0.4.0**  
   - Arduino name changed from `OSP 2-wire SPI - aospi` to `OSP 2wireSPI aospi`.
   - Added link for traces.
-  - Added blue slave line in BiDir diagram (`dirbidir.drawio.png`) and green dashed OSP32 border line in OPS32 diagram (`dirosp32.drawio.png`).
+  - Added blue slave line in BiDir diagram (`dirbidir.drawio.png`) and green dashed OSP32 border line in OSP32 diagram (`dirosp32.drawio.png`).
   - Renamed dir `extra` to `extras`.
   - Small corrections in readme.md.
   - Added (for board testing) `aospi_outoena_set()`/`aospi_outoena_get()` and `aospi_inoena_set()`/`aospi_inoena_get()`.

examples/aospi_bringup/extras/slicer.png

@@ -27,7 +27,7 @@
 
 
 // Identifies lib version
-#define AOSPI_VERSION "0.5.6"
+#define AOSPI_VERSION "0.5.7"
 
 
 // OSP uses telegrams of max 12 bytes