SPIDriver.md

@@ -25,6 +25,7 @@ Aggregates all the objects needed by a driver to access a bus.
 
 ## Examples
 ### High level acccess through SPITransaction
+In this example, SPIDriver is used to write and read 1 byte from two sensors. The bus is configured differently for each sensor.
 ```cpp
 // Creates an SPIBus object using the SPI5 peripheral
 // The SPIBus object is shared among all slaves on the bus
@@ -52,7 +53,7 @@ int main()
                                                     // The bus is immediately configured here
             t1.write(0x25, 69); // Writes 69 in the 0x25 register        
             uint8_t val = t1.read(0x26); // Reads the 0x26 register
-
+            printf("Sensor 1: %d\n", (int)val);
             // End of scope: the SPITransaction is terminated here.
        }
        // Operations with slave 2
@@ -62,6 +63,7 @@ int main()
 
             t2.write(0x45, 123); // Writes in the 0x45 register        
             uint8_t val = t2.read(0x70); // Reads the 0x70 register
+            printf("Sensor 2: %d\n", (int)val);
 
             // End of scope: the SPITransaction is terminated here.
        }
@@ -73,7 +75,7 @@ int main()
 ```
 
 ### Low level acccess through SPIBusInterface
-In this example, the same operations are performed, but directly using `SPIBusInterface` instead of `SPITransaction`
+In this example, exactly the same operations are performed, but directly using `SPIBusInterface` instead of `SPITransaction`
 ```cpp
 // Creates an SPIBus object using the SPI5 peripheral
 // The SPIBus object is shared among all slaves on the bus
@@ -100,19 +102,22 @@ int main()
        uint8_t data = 69;
 
        bus.configure(cfg_s1); // Configure the bus for slave 1
+
+       // Write one byte
        bus.select(cs_s1); // Assert CS
- 
        bus.write(&reg, 1); // Write the register address
        bus.write(&data, 1); // Write the data to be put in the register
-
        bus.deselect(cs_s1); // Clear CS
 
+       // Read one byte
        reg = 0x26 | 0x80; // Specify the register we want to read, set the MSB to 1 to signal a read operation
        uint8_t val;
        bus.select(cs_s1);
        bus.write(&reg, 1); // Write register address
        bus.read(&val, 1); // Read 1 byte into val
        bus.deselect(cs_s1);
+       
+       printf("Sensor 1: %d\n", (int)val);
 
 
        // Operation with slave 2
@@ -120,13 +125,14 @@ int main()
        data = 123;
 
        bus.configure(cfg_s2); // Configure the bus for slave 2
+
+       // Write one byte
        bus.select(cs_s2); // Assert CS
- 
        bus.write(&reg, 1); // Write the register address
        bus.write(&data, 1); // Write the data to be put in the register
-
        bus.deselect(cs_s2); // Clear CS
 
+       // Read one byte
        reg = 0x70 | 0x80; // Specify the register we want to read, set the MSB to 1 to signal a read operation
        uint8_t val;
 
@@ -134,6 +140,9 @@ int main()
        bus.write(&reg, 1);
        bus.read(&val, 1);
        bus.deselect(cs_s2);
+
+       printf("Sensor 2: %d\n", (int)val);
+
    }
 
    return 0; 
@@ -143,7 +152,10 @@ int main()
 ### Notes
 - The `SPIBus` object must be shared by all slaves on the same bus. Do not create multiple instances of the class `SPIBus` for each sensor.
 - But each slave can have different configurations
-- SPITransactions must be scoped (if not, in this example, the bus may be configured for slave 2 before the operations with slave 1 are performed)
+- SPITransactions must be scoped (if not, in the first example, the bus may be configured for *slave 2* before the operations with *slave 1* are performed)
 - Access through `SPIBusInterface` (second example) is discouraged due to its complexity and because it is error-prone (easy to forget to configure / select / deselect). But it may be necessary in some cases (sensors with non-standard SPI implementation)
 - Operations on the same bus must be synchronized between multiple threads. It is strongly recommended to perform operations from a single thread to avoid synchronization problems.
 
+## Further examples
+See `tests/drivers/test-l3gd20.cpp` and `shared/Sensors/L3GD20.h` for a real life example of using SPIDriver to sample a gyroscope.
+