docs: update documentation [#2]

README.md

@@ -4,13 +4,13 @@
 [Application Board 3.1](https://www.bosch-sensortec.com/software-tools/tools/application-board-3-1/) or 
 [3.0](https://www.bosch-sensortec.com/software-tools/tools/application-board-3-0/) hardware.
 
-Install the latest version from pypi:
+Install the latest version from [pypi](https://pypi.org/):
 ```bash
 pip install umrx-v3-py
 ```
 
 The `umrx-v3-py` project implements in `python3` COINES communication protocol 
-to control the MCU and read the sensor data from the 
+to control the micro-controller (MCU) and read the sensor data from the 
 [Application Board 3.1](https://www.bosch-sensortec.com/software-tools/tools/application-board-3-1/) and 
 [3.0](https://www.bosch-sensortec.com/software-tools/tools/application-board-3-0/) when 
 board is programmed with BST default firmware.
@@ -27,7 +27,7 @@ and
 * Support [Application Board 3.1](https://www.bosch-sensortec.com/software-tools/tools/application-board-3-1/) 
   and 
   [Application Board 3.0](https://www.bosch-sensortec.com/software-tools/tools/application-board-3-0/);
-* Configure shuttle pins, set logical level;
+* Configure shuttle pins, set pin levels;
 * Switch ON/OFF `VDD` and `VDDIO` of the shuttle board to power the sensor;
 * Read / write the sensor registers using the I2C protocol;
 * Read / write the sensor registers using the SPI protocol;
@@ -45,7 +45,7 @@ and
 Communication with firmware happens either via USB (for Application Board 3.0) 
 or serial port over USB (for Application Board 3.1).
 Reading / writing USB (or serial) devices is often a privileged operation. 
-Below we describe how to run the code as a regular user (without root privileges).
+Below we describe OS-specific setup steps to be able to use the package. 
 
 ### OS prerequisites
 
@@ -87,16 +87,39 @@ Reload the udev-rules:
 sudo udevadm control --reload-rules && sudo udevadm trigger
 ```
 
-To access serial device on Linux as a regular user, one needs to be a member of `dialout` group.
+To access serial devices on Linux as a regular user, one needs to be a member of the `dialout` group.
 
 ```bash
 sudo usermod -a -G dialout <your-user-name>
 ```
 
 #### Windows
 
+Install [libusb-1](https://github.com/libusb/libusb) via `vcpkg` by following 
+these [instructions](https://github.com/libusb/libusb/wiki/Windows#user-content-vcpkg_port).
+
+Add the path where the `*.DLL` libraries are located to the `PATH` environment variable.
+
+Use [`zadig`](https://zadig.akeo.ie/) to install the drivers for the boards:
+
+* For Application Board 3.1 install CDC serial driver:
+
+* For Application Board 3.0 install WinUSB:
+
+
+
 #### Mac OS
 
+Install [Homebrew](https://brew.sh/).
+
+Install [libusb](https://formulae.brew.sh/formula/libusb):
+```bash
+brew install libusb
+```
+
+
+Execute the python scripts with `sudo` to read/write USB device.
+
 ### Install using pip
 
 ```bash
@@ -115,16 +138,146 @@ poetry install
 poetry shell
 ```
 
-
 ## Supported python version
 
 The project was developed with `python-3.12` although it might work earlier python versions `>=3.9`.
 
+## Quick start
+
+The examples below are self-contained and can be copy-pasted as is.
 
+### Terminology
 
-## Quick start
+Bosch offers two hardware revisions:
+* [Application Board 3.1](https://www.bosch-sensortec.com/software-tools/tools/application-board-3-1/), **3.1** HW
+* [Application Board 3.0](https://www.bosch-sensortec.com/software-tools/tools/application-board-3-0/), **3.0** HW
+
+Although both boards use [`nRF52840`](https://www.nordicsemi.com/Products/nRF52840)
+(and are based on [`NINA-B30*`](https://www.u-blox.com/en/product/nina-b30-series-open-cpu-0) modules),
+they differ in hardware and firmware.
+
+In `umrx-v3-py` code to differentiate the boards we use 
+`v3_rev1` (for _v3, revision 1_) suffix for **3.1** HW
+and 
+`v3_rev0` (for _v3, revision 0_) suffix for **3.0** HW.
+
+### Create the board object
+
+Create the board object and initialize (connect to board and open communication):
+
+```python
+from umrx_app_v3.mcu_board.app_board_v3_rev1 import ApplicationBoardV3Rev1
+
+board = ApplicationBoardV3Rev1()
+# initialize board communication 
+board.initialize()
+```
+
+### Configure shuttle pins
+
+```python
+from umrx_app_v3.mcu_board.app_board_v3_rev1 import ApplicationBoardV3Rev1
+from umrx_app_v3.mcu_board.bst_protocol_constants import MultiIOPin, PinDirection, PinValue
+
+board = ApplicationBoardV3Rev1()
+board.initialize()
+# configure shuttle pin P2.6 as output and set to high 
+board.set_pin_config(MultiIOPin.MINI_SHUTTLE_PIN_2_6, PinDirection.OUTPUT, PinValue.HIGH)
+```
+
+### Supply power to shuttle
+
+```python
+from umrx_app_v3.mcu_board.app_board_v3_rev1 import ApplicationBoardV3Rev1
+
+board = ApplicationBoardV3Rev1()
+board.initialize()
+# set VDD to 3.3 V, VDDIO to 3.3 V
+board.set_vdd_vddio(3.3, 3.3)
+```
+
+### Configure communication interface
+
+#### I2C
+
+```python
+import time
+from umrx_app_v3.mcu_board.app_board_v3_rev1 import ApplicationBoardV3Rev1
+from umrx_app_v3.mcu_board.bst_protocol_constants import MultiIOPin, PinDirection, PinValue
+
+board = ApplicationBoardV3Rev1()
+board.initialize()
+board.set_pin_config(MultiIOPin.MINI_SHUTTLE_PIN_2_6, PinDirection.OUTPUT, PinValue.HIGH)
+board.set_vdd_vddio(3.3, 3.3)
+time.sleep(0.01)
+board.configure_i2c()
+```
+
+#### SPI
+
+```python
+import time
+from umrx_app_v3.mcu_board.app_board_v3_rev1 import ApplicationBoardV3Rev1
+from umrx_app_v3.mcu_board.bst_protocol_constants import MultiIOPin, PinDirection, PinValue, SPIBus
+from umrx_app_v3.mcu_board.commands.spi import SPIConfigureCmd
+
+board = ApplicationBoardV3Rev1()
+board.initialize()
+board.set_pin_config(MultiIOPin.MINI_SHUTTLE_PIN_2_1, PinDirection.OUTPUT, PinValue.HIGH)
+board.set_pin_config(MultiIOPin.MINI_SHUTTLE_PIN_2_5, PinDirection.OUTPUT, PinValue.HIGH)
+board.set_pin_config(MultiIOPin.MINI_SHUTTLE_PIN_2_6, PinDirection.OUTPUT, PinValue.LOW)
+board.set_vdd_vddio(3.3, 3.3)
+time.sleep(0.01)
+SPIConfigureCmd.set_bus(SPIBus.BUS_1)
+board.configure_spi()
+```
+
+### Read / write registers
+
+#### I2C
+```python
+import time
+from umrx_app_v3.mcu_board.app_board_v3_rev1 import ApplicationBoardV3Rev1
+from umrx_app_v3.mcu_board.bst_protocol_constants import MultiIOPin, PinDirection, PinValue
+
+board = ApplicationBoardV3Rev1()
+board.initialize()
+board.start_communication()
+board.set_pin_config(MultiIOPin.MINI_SHUTTLE_PIN_2_6, PinDirection.OUTPUT, PinValue.HIGH)
+board.set_vdd_vddio(3.3, 3.3)
+time.sleep(0.1)
+board.configure_i2c()
+time.sleep(0.1)
+result = board.read_i2c(i2c_address=0x68, register_address=0x0, bytes_to_read=1)
+print(result)
+```
+#### SPI
+
+```python
+import time
+from umrx_app_v3.mcu_board.app_board_v3_rev1 import ApplicationBoardV3Rev1
+from umrx_app_v3.mcu_board.bst_protocol_constants import MultiIOPin, PinDirection, PinValue, SPIBus
+from umrx_app_v3.mcu_board.commands.spi import SPIConfigureCmd
+
+board = ApplicationBoardV3Rev1()
+board.initialize()
+board.set_pin_config(MultiIOPin.MINI_SHUTTLE_PIN_2_6, PinDirection.OUTPUT, PinValue.HIGH)
+board.set_vdd_vddio(3.3, 3.3)
+time.sleep(0.01)
+SPIConfigureCmd.set_bus(SPIBus.BUS_1)
+board.configure_spi()
+result = board.read_spi(cs_pin=MultiIOPin.MINI_SHUTTLE_PIN_2_5, register_address=0x0, bytes_to_read=2)
+print(result)
+```
+
+### Examples
+
+Take a look at the additional [examples](./examples).
 
-Create the 
+## Default firmware
 
-Look at the available [examples](./examples).
+The code was developed and tested with the _default_ firmware the **3.0** and **3.1** boards
+were pre-programmed with.
 
+If you want to program you board with the same firmware, follow instructions from this 
+[repo](https://github.com/umrx-sw/bst-default-firmware).

examples/README.md

@@ -18,6 +18,6 @@ board:
 * [`bmi088/bmi088_spi_interrupt_streaming.py`](./bmi088/bmi088_spi_interrupt_streaming.py)
 
 
-**Need a specific example or do not know how to read data from your sensor?**
+## Need a specific example or do not know how to read data from your sensor?
 
-Let We are happy to help and offer our consulting and development expertise.
+Let us know, we are happy to help and offer our development expertise.