Updates along with SDK1.3.0 release (#181)

Bug fixes and new examples

Co-authored-by: Paulo Marques <pm@quant-insight.com>
Co-authored-by: martin <admin@crossleys.biz>
Co-authored-by: matiasilva <matias.silva@raspberrypi.com>
Co-authored-by: Uri Shaked <uri@urishaked.com>
Co-authored-by: Diego Solano <diegosolano@gmail.com>
Co-authored-by: Andrew Scheller <andrew.scheller@raspberrypi.com>
Co-authored-by: Adrian Hesketh <a-h@users.noreply.github.com>
Co-authored-by: Emircan Gündoğdu <58917386+emircangun@users.noreply.github.com>
Co-authored-by: Josef Wegner <80200012+josefwegner@users.noreply.github.com>
Co-authored-by: pmarques-dev <72901351+pmarques-dev@users.noreply.github.com>
Co-authored-by: Paulo Marques <pm@quant-insight.com>
Co-authored-by: mjcross <mjcross@users.noreply.github.com>
Co-authored-by: martin <admin@crossleys.biz>

i2c/lis3dh_i2c/CMakeLists.txt

@@ -0,0 +1,12 @@
+add_executable(lis3dh_i2c
+        lis3dh_i2c.c
+        )
+
+# pull in common dependencies and additional i2c hardware support
+target_link_libraries(lis3dh_i2c pico_stdlib hardware_i2c)
+
+# create map/bin/hex file etc.
+pico_add_extra_outputs(lis3dh_i2c)
+
+# add url via pico_set_program_url
+example_auto_set_url(lis3dh_i2c)

i2c/lis3dh_i2c/README.adoc

@@ -0,0 +1,39 @@
+= Attaching a LIS3DH Nano Accelerometer via i2c.
+
+This example shows you how to interface the Raspberry Pi Pico to the LIS3DH accelerometer and temperature sensor.
+======
+The code reads and displays the acceleration values of the board in the 3 axes and the ambient temperature value. The datasheet for the sensor can be found at https://www.st.com/resource/en/datasheet/cd00274221.pdf. The device is being operated on 'normal mode' and at a frequency of 1.344 kHz (this can be changed by editing the ODR bits of CTRL_REG4). The range of the data is controlled by the FS bit in CTRL_REG4 and is equal to ±2g in this example. The sensitivity depends on the operating mode and data range; exact values can be found on page 10 of the datasheet. In this case, the sensitivity value is 4mg (where g is the value of gravitational acceleration on the surface of Earth). In order to use the auxiliary ADC to read temperature, the we must set the BDU bit to 1 in CTRL_REG4 and the ADC_EN bit to 1 in TEMP_CFG_REG. Temperature is communicated through ADC 3. 
+======
+[NOTE]
+======
+The sensor doesn't have features to eliminate any offsets in the data and they would be needed to be taken into account in the code. 
+======
+
+
+== Wiring information
+
+Wiring up the device requires 4 jumpers, to connect VIN, GND, SDA and SCL. The example here uses I2C port 0, which is assigned to GPIO 4 (SDA) and 5 (SCL) in software. Power is supplied from the 3V pin.
+
+
+[[lis3dh_i2c_wiring]]
+[pdfwidth=75%]
+.Wiring Diagram for LIS3DH.
+image::lis3dh_i2c.png[]
+
+== List of Files
+
+CMakeLists.txt:: CMake file to incorporate the example in to the examples build tree.
+lis3dh_i2c.c:: The example code.
+
+== Bill of Materials
+
+.A list of materials required for the example
+[[lis3dh-bom-table]]
+[cols=3]
+|===
+| *Item* | *Quantity* | Details
+| Breadboard | 1 | generic part
+| Raspberry Pi Pico | 1 | https://www.raspberrypi.com/products/raspberry-pi-pico/
+| LIS3DH board| 1 | https://www.adafruit.com/product/2809
+| M/M Jumper wires | 4 | generic part
+|===

i2c/lis3dh_i2c/lis3dh_i2c.c

@@ -0,0 +1,129 @@
+/**
+ * Copyright (c) 2020 Raspberry Pi (Trading) Ltd.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include <stdio.h>
+#include <string.h>
+#include "pico/stdlib.h"
+#include "pico/binary_info.h"
+#include "hardware/i2c.h"
+
+/* Example code to talk to a LIS3DH Mini GPS module.
+
+   This example reads data from all 3 axes of the accelerometer and uses an auxillary ADC to output temperature values.
+
+   Connections on Raspberry Pi Pico board, other boards may vary.
+
+   GPIO PICO_DEFAULT_I2C_SDA_PIN (On Pico this is 4 (physical pin 6)) -> SDA on LIS3DH board
+   GPIO PICO_DEFAULT_I2C_SCK_PIN (On Pico this is 5 (physical pin 7)) -> SCL on LIS3DH board
+   3.3v (physical pin 36) -> VIN on LIS3DH board
+   GND (physical pin 38)  -> GND on LIS3DH board
+*/
+
+// By default this device is on bus address 0x18
+
+const int ADDRESS = 0x18;
+const uint8_t CTRL_REG_1 = 0x20;
+const uint8_t CTRL_REG_4 = 0x23;
+const uint8_t TEMP_CFG_REG = 0xC0;
+
+#ifdef i2c_default
+
+void lis3dh_init() {
+    uint8_t buf[2];
+
+    // Turn normal mode and 1.344kHz data rate on
+    buf[0] = CTRL_REG_1;
+    buf[1] = 0x97;
+    i2c_write_blocking(i2c_default, ADDRESS, buf, 2, false);
+
+    // Turn block data update on (for temperature sensing)
+    buf[0] = CTRL_REG_4;
+    buf[1] = 0x80;
+    i2c_write_blocking(i2c_default, ADDRESS, buf, 2, false);
+
+    // Turn auxillary ADC on
+    buf[0] = TEMP_CFG_REG;
+    buf[1] = 0xC0;
+    i2c_write_blocking(i2c_default, ADDRESS, buf, 2, false);
+}
+
+void lis3dh_calc_value(uint16_t raw_value, float *final_value, bool isAccel) {
+    // Convert with respect to the value being temperature or acceleration reading 
+    float scaling;
+    float senstivity = 0.004f; // g per unit
+
+    if (isAccel == true) {
+        scaling = 64 / senstivity;
+    } else {
+        scaling = 64;
+    }
+
+    // raw_value is signed
+    *final_value = (float) ((int16_t) raw_value) / scaling;
+}
+
+void lis3dh_read_data(uint8_t reg, float *final_value, bool IsAccel) {
+    // Read two bytes of data and store in a 16 bit data structure
+    uint8_t lsb;
+    uint8_t msb;
+    uint16_t raw_accel;
+    i2c_write_blocking(i2c_default, ADDRESS, &reg, 1, true);
+    i2c_read_blocking(i2c_default, ADDRESS, &lsb, 1, false);
+
+    reg |= 0x01;
+    i2c_write_blocking(i2c_default, ADDRESS, &reg, 1, true);
+    i2c_read_blocking(i2c_default, ADDRESS, &msb, 1, false);
+
+    raw_accel = (msb << 8) | lsb;
+
+    lis3dh_calc_value(raw_accel, final_value, IsAccel);
+}
+
+#endif
+
+int main() {
+    stdio_init_all();
+#if !defined(i2c_default) || !defined(PICO_DEFAULT_I2C_SDA_PIN) || !defined(PICO_DEFAULT_I2C_SCL_PIN)
+#warning i2c/lis3dh_i2c example requires a board with I2C pins
+    puts("Default I2C pins were not defined");
+#else
+    printf("Hello, LIS3DH! Reading raw data from registers...\n");
+
+    // This example will use I2C0 on the default SDA and SCL pins (4, 5 on a Pico)
+    i2c_init(i2c_default, 400 * 1000);
+    gpio_set_function(PICO_DEFAULT_I2C_SDA_PIN, GPIO_FUNC_I2C);
+    gpio_set_function(PICO_DEFAULT_I2C_SCL_PIN, GPIO_FUNC_I2C);
+    gpio_pull_up(PICO_DEFAULT_I2C_SDA_PIN);
+    gpio_pull_up(PICO_DEFAULT_I2C_SCL_PIN);
+    // Make the I2C pins available to picotool
+    bi_decl(bi_2pins_with_func(PICO_DEFAULT_I2C_SDA_PIN, PICO_DEFAULT_I2C_SCL_PIN, GPIO_FUNC_I2C));
+
+    float x_accel, y_accel, z_accel, temp;
+
+    lis3dh_init();
+
+    while (1) {
+        lis3dh_read_data(0x28, &x_accel, true);
+        lis3dh_read_data(0x2A, &y_accel, true);
+        lis3dh_read_data(0x2C, &z_accel, true);
+        lis3dh_read_data(0x0C, &temp, false);
+
+        // Display data 
+        printf("TEMPERATURE: %.3f%cC\n", temp, 176);
+        // Acceleration is read as a multiple of g (gravitational acceleration on the Earth's surface)
+        printf("ACCELERATION VALUES: \n");
+        printf("X acceleration: %.3fg\n", x_accel);
+        printf("Y acceleration: %.3fg\n", y_accel);
+        printf("Z acceleration: %.3fg\n", z_accel);
+
+        sleep_ms(500);
+
+        // Clear terminal 
+        printf("\e[1;1H\e[2J");
+    }
+#endif
+    return 0;
+}