CrossWorks Device Library

Transcription

1 Version: Rowley Associates Limited

2 2

3 Contents Contents Protocol API Reference <ctl_bus.h> CTL_PARALLEL_BUS_t ctl_bus_lock ctl_bus_lock_ex ctl_bus_read ctl_bus_read_bit ctl_bus_set_direction ctl_bus_set_input_mode ctl_bus_set_output_mode ctl_bus_unlock ctl_bus_write ctl_bus_write_bit ctl_bus_write_bits ctl_parallel_bus_initialize <ctl_i2c.h> CTL_I2C_BUS_t CTL_I2C_FAST_MODE_PLUS_SPEED CTL_I2C_FAST_MODE_SPEED CTL_I2C_REQUEST_t CTL_I2C_STANDARD_SPEED ctl_i2c_lock_bus

4 Contents ctl_i2c_lock_bus_ex ctl_i2c_read ctl_i2c_set_speed ctl_i2c_unlock_bus ctl_i2c_write ctl_i2c_write_read <ctl_spi.h> CTL_SPI_BUS_t CTL_SPI_DEVICE_t CTL_SPI_EXCHANGE_FN_t CTL_SPI_MODE_t CTL_SPI_PROTOCOL_t CTL_SPI_SET_PROTOCOL_FN_t ctl_spi_attach_device ctl_spi_deselect_device ctl_spi_detach_device ctl_spi_exchange ctl_spi_get ctl_spi_issue_deselected_clocks ctl_spi_lock_bus ctl_spi_lock_bus_ex ctl_spi_put ctl_spi_put_get ctl_spi_read ctl_spi_select_device ctl_spi_set_idle ctl_spi_set_mode ctl_spi_set_protocol ctl_spi_set_speed ctl_spi_set_width ctl_spi_unlock_bus ctl_spi_write <ctl_sensors.h> CTL_ACCELEROMETER_t CTL_AXIS_TRANSFORMATION CTL_GYROSCOPE_t CTL_HUMIDITY_SENSOR_t CTL_IMU_t CTL_LIGHT_SENSOR_t CTL_MAGNETOMETER_t CTL_PRESSURE_SENSOR_t

5 Contents CTL_TEMPERATURE_SENSOR_t ctl_accelerometer_measure ctl_accelerometer_set_bandwidth ctl_accelerometer_set_range ctl_forward_transform_axes ctl_generate_axis_transform ctl_gyroscope_measure ctl_gyroscope_set_bandwidth ctl_gyroscope_set_range ctl_humidity_sensor_measure ctl_light_sensor_measure ctl_magnetometer_measure ctl_magnetometer_set_bandwidth ctl_pressure_sensor_measure ctl_temperature_sensor_measure ctl_temperature_sensor_set_resolution <ctl_transport.h> CTL_TRANSPORT_BUS_t CTL_TRANSPORT_t ctl_transport_initialize_i2c ctl_transport_initialize_spi ctl_transport_lock ctl_transport_read_16b_register ctl_transport_read_24b_register ctl_transport_read_32b_register ctl_transport_read_8b_register ctl_transport_read_registers ctl_transport_read_registers_fail ctl_transport_read_registers_i2c ctl_transport_rmw_16b_register ctl_transport_rmw_24b_register ctl_transport_rmw_32b_register ctl_transport_rmw_8b_register ctl_transport_unlock ctl_transport_write_16b_register ctl_transport_write_24b_register ctl_transport_write_32b_register ctl_transport_write_8b_register ctl_transport_write_registers ctl_transport_write_registers_fail ctl_transport_write_registers_i2c

6 Contents <ctl_uart.h> ctl_uart_getc ctl_uart_getc_nb ctl_uart_putc ctl_uart_puts Device API Reference Analog <adc101s021.h> adc101s021_init adc101s021_measure_raw <ltc2309.h> LTC2309_I2C_ADDR ltc2309_init_i2c ltc2309_sample_differential_bipolar ltc2309_sample_differential_unipolar ltc2309_sample_single_ended_bipolar ltc2309_sample_single_ended_unipolar Digital <mcp23016.h> MCP23016_I2C_ADDR mcp23016_initialize_i2c <mcp23x08.h> MCP23008_I2C_ADDR mcp23x08_initialize_i2c mcp23x08_initialize_spi <mcp23x17.h> MCP23017_I2C_ADDR mcp23x17_initialize_i2c mcp23x17_initialize_spi <pca9532.h> PCA9532_I2C_ADDR pca9532_initialize_i2c pca9532_led_mode pca9532_set_duty_cycle pca9532_set_led_mode pca9532_set_pwm_frequency <pca9672.h> pca9672_initialize_i2c <pcf8575.h> PCF8575_I2C_ADDR pcf8575_initialize_i2c

7 Contents Clock <ltc6904.h> LTC6904_I2C_ADDR_ADR LTC6904_I2C_ADDR_ADR LTC6904_MODE_CLK_OFF_nCLK_ON LTC6904_MODE_CLK_ON_nCLK_OFF LTC6904_MODE_CLK_ON_nCLK_ON LTC6904_MODE_POWER_DOWN LTC6904_OSCILLATOR_t ltc6904_get_selected_frequency ltc6904_init_i2c ltc6904_set_frequency ltc6904_set_mode Environmental <adt7410.h> ADT7410_I2C_ADDR adt7410_initialize_i2c <bmp085.h> BMP085_BAROMETER_t BMP085_I2C_ADDR bmp085_initialize_i2c bmp085_set_resolution <dht.h> dht_read_humidity <hih6130.h> HIH6130_I2C_ADDR hih6130_initialize_i2c <isl29023.h> ISL29023_DRIVER_t ISL29023_I2C_ADDR isl29023_initialize_i2c isl29023_set_range isl29023_set_resolution_bits <lm75.h> LM75_I2C_ADDR lm75_initialize_i2c lm75_initialize_i2c_ex <lps331ap.h> LPS331AP_I2C_ADDR lps331ap_initialize_i2c <ltr501als.h>

8 Contents LTR501ALS_I2C_ADDR ltr501als_initialize_i2c <max6675.h> max6675_initialize_spi <mpl115a.h> MPL115A2_I2C_ADDRESS mpl115a_initialize_i2c mpl115a_initialize_spi <mpl3115a2.h> MPL3115A2_I2C_ADDRESS mpl3115a2_initialize_i2c <sht1x.h> SHT1X_HIGH_RESOLUTION SHT1X_LOW_RESOLUTION sht1x_initialize sht1x_read_linear_humidity sht1x_read_raw_humidity sht1x_read_raw_temperature sht1x_read_status sht1x_read_temperature sht1x_read_true_humidity sht1x_set_resolution sht1x_set_supply_voltage sht1x_soft_reset sht1x_write_status <sht2x.h> SHT2x_I2C_ADDR SHT2x_RESOLUTION_t sht2x_get_resolution sht2x_initialize_i2c sht2x_read_user sht2x_set_resolution sht2x_write_user <si7005.h> SI7005_I2C_ADDR si7005_initialize_i2c <tmp100.h> TMP100_I2C_ADDR tmp100_initialize_i2c <tmp102.h> TMP102_I2C_ADDR

9 Contents TMP275_I2C_ADDR tmp102_initialize_i2c tmp102_set_extended_mode <tsl2561.h> TSL2561_DRIVER_t TSL2561_I2C_ADDR_FLOAT TSL2561_I2C_ADDR_GND TSL2561_I2C_ADDR_VDD tsl2561_initialize_i2c tsl2561_set_integration_time HMI <ads7846.h> ads7846_init <hd44780.h> HD44780_4BIT_INTERFACE HD44780_ANSI_DRIVER_t HD44780_BIDIRECTIONAL_DBUS HD44780_DRIVER_t hd44780_ansi_init hd44780_clear hd44780_cursor_off hd44780_cursor_on hd44780_display_off hd44780_display_on hd44780_putc hd44780_puts hd44780_reset hd44780_send_cmd hd44780_set_backlight hd44780_set_cursor_position hd44780_write <mpr121.h> MPR121_ADDRESS_SCL MPR121_ADDRESS_SDA MPR121_ADDRESS_VDD MPR121_ADDRESS_VSS <wii_controller.h> WII_CLASSIC_REPORT_t WII_NUNCHUK_REPORT_t wii_classic_sample wii_extension_controller_initialize

10 Contents wii_extension_controller_read_memory wii_extension_controller_write_memory_byte wii_nunchuk_accelerometer_interface wii_nunchuk_sample Magnetics <ak8975.h> AK8975_I2C_ADDR ak8975_initialize_i2c ak8975_initialize_transport <bmm150.h> BMM150_I2C_ADDR bmm150_initialize_i2c bmm150_initialize_spi <fxos8700cq.h> FXOS8700CQ_I2C_ADDR FXOS8700CQ_t fxos8700cq_initialize_i2c <hmc5843.h> HMC5843_I2C_ADDR hmc5843_initialize_i2c <hmc5883l.h> HMC5883L_I2C_ADDR hmc5883l_initialize_i2c hmc5883l_initialize_transport <hmc6343.h> HMC6343_I2C_ADDR hmc6343_read_heading <hmc6352.h> HMC6352_I2C_ADDR hmc6352_read_heading <mag3110.h> MAG3110_I2C_ADDR mag3110_initialize_i2c mag3110_read_die_temperature mag3110_set_oversampling_ratio Motion <adxl345.h> ADXL345_I2C_ADDR_ALTERNATE ADXL345_I2C_ADDR_DEFAULT adxl345_initialize_i2c adxl345_initialize_spi

11 Contents <adxl362.h> adxl362_initialize_spi <atavrsbin1.h> ATAVRSBIN1_t atavrsbin1_initialize_i2c <atavrsbin2.h> ATAVRSBIN2_t atavrsbin2_initialize_i2c <bma150.h> BMA150_I2C_ADDR bma150_initialize_i2c bma150_initialize_spi bma150_read_chip_id bma150_read_die_temperature bma150_soft_reset <bma250.h> BMA250_I2C_ADDR bma250_initialize_i2c bma250_initialize_spi bma250_read_chip_id bma250_read_die_temperature <imu3000.h> IMU3000_I2C_ADDR imu3000_initialize_i2c imu3000_read_die_temperature <imu3000_combo.h> IMU3000_COMBO_t imu3000_combo_initialize_i2c <itg3200.h> ITG3200_I2C_ADDR itg3200_initialize_i2c itg3200_read_die_temperature <kxp84.h> KXP84_I2C_ADDR kxp84_initialize_i2c kxp84_initialize_spi <kxtf9.h> KXTF9_I2C_ADDR kxtf9_initialize_i2c <l3g4200d.h> L3G4200D_I2C_ADDR

12 Contents l3g4200d_initialize_i2c <l3gd20.h> L3GD20_I2C_ADDR l3gd20_initialize_i2c <lis302dl.h> LIS302DL_I2C_ADDR lis302dl_initialize_i2c lis302dl_initialize_spi <lis331dlh.h> LIS331DLH_I2C_ADDR lis331dlh_initialize_i2c lis331dlh_initialize_spi <lis331hh.h> LIS331HH_I2C_ADDR lis331hh_initialize_i2c lis331hh_initialize_spi <lis3dsh.h> LIS3DSH_I2C_ADDR lis3dsh_initialize_i2c lis3dsh_initialize_spi <lis3lv02dl.h> LIS3LV02DL_I2C_ADDR lis3lv02dl_initialize_i2c lis3lv02dl_initialize_spi <mma7455l.h> MMA7455_I2C_ADDR mma7455l_initialize_i2c mma7455l_initialize_spi <mma7660fc.h> MMA7660FC_I2C_ADDR mma7660fc_initialize_i2c <mma845xq.h> MMA8451Q_I2C_ADDR mma8451q_initialize_i2c <mma8491q.h> MMA8491Q_I2C_ADDR mma8491q_initialize_i2c <mpu6000.h> MPU6000_I2C_ADDR MPU6000_t mpu6000_aux_transport_setup

13 Contents mpu6000_initialize_i2c mpu6000_initialize_spi mpu6000_read_die_temperature mpu6000_revision <sca3000.h> sca3000_initialize_i2c sca3000_initialize_spi

14 Contents 14

15 The contains pre-written, tested device driver software to interact with a range of common sensors and devices. This library will be extended over time, as more devices become available and are considered for inclusion in the library. The device library is split into two parts: Protocol API: provides an abstract interface to common industry protocols, such as I2C and SPI, along with an API for generic sensor functions. Device API: provides specific device implementations for the generic sensor functions and drivers for unique or special devices. Architecture The is one part of the CrossWorks Target Library. Many of the low-level functions provided by the target library are built using features of the CrossWorks Tasking Library for multi-threaded operation. Delivery format The is delivered in source form. License The source files in this package are not public domain and are not open source. They represent a substantial investment undertaken by Rowley Associates to assist CrossWorks customers in prototyping solutions using well-written, tested drivers. 15

16 If you hold a paid-for CrossWorks Version 3 or later commercial license, you are free to compile this package and incorporate the resulting object code in your own products without royalties and without additional license fees. Customers holding a CrossWorks Version 1 or 2 commercial license are required to upgrade to CrossWorks Version 3 to use this software. If you hold a paid-for CrossWorks Version 3 or later non-commercial license, you are free to compile this package and incorporate the resulting object code in your own projects, for your own use, without royalties and without additional license fees. You are, however, prohibited from distributing the linked code, incorporating the object code from this library, in binary form. Customers holding a CrossWorks Version 1 or 2 non-commercial license are required to purchase CrossWorks Version 3 to use this software. Feedback This facility is a work in progress and may undergo rapid change. If you have comments, observations, suggestions, or problems, please feel free to air them on the CrossWorks Target and Platform API discussion forum. 16

17 <ctl_bus.h> Overview Abstract parallel digital bus. The types and functions in <ctl_i2c.h> provide a high-level set of services that implement a parallel bus. The provides drivers for the following devices that implement a parallel bus but are connected using I2C or SPI: MCP23x08 MCP23016 MCP23x17 PCF8575 PCA9672 API Summary Bus CTL_PARALLEL_BUS_t ctl_bus_lock ctl_bus_lock_ex ctl_bus_unlock ctl_parallel_bus_initialize Configuration ctl_bus_set_direction ctl_bus_set_input_mode ctl_bus_set_output_mode I/O ctl_bus_read ctl_bus_read_bit ctl_bus_write ctl_bus_write_bit ctl_bus_write_bits Abstract parallel bus interface Acquire exclusive bus lock Acquire exclusive bus lock (extended) Release exclusive bus lock Initialize structure Set bus input-output direction Set selected bus bits to input direction Set selected bus bits to output direction Read entire bus Read a single bit from bus Write entire bus output Write a single bit to bus Write bits to bus through a mask 17

18 CTL_PARALLEL_BUS_t typedef struct { CTL_TRANSPORT_t transport; CTL_STATUS_t (*set_direction)(ctl_parallel_bus_s *, unsigned); CTL_STATUS_t (*write)(ctl_parallel_bus_s *, unsigned); CTL_STATUS_t (*read)(ctl_parallel_bus_s *); CTL_MUTEX_t *mutex; unsigned width; unsigned output; unsigned direction; unsigned mask; } CTL_PARALLEL_BUS_t; CTL_PARALLEL_BUS_t contains the bus state and methods that implement a parallel bus. Clients that use the parallel bus should consider all data in this structure private. Structure transport Underlying transport for parallel buses realized by I2C or SPI devices. set_direction Method to set the bus direction. write Method to set the bus pins. read Method to read the bus pins. width The bus width, in bits. output The bus output state. direction The bus direction. mask The bus mask corresponding to width. 18

19 ctl_bus_lock void ctl_bus_lock(ctl_parallel_bus_t *self); ctl_bus_lock acquires the bus lock mutex of the bus self. If there is no mutex associated with the bus self, ctl_bus_lock returns immediately indicating success. All locks of the bus by ctl_bus_lock must be paired with a call to ctl_bus_unlock to release the lock. Note Because mutexes can be locked multiple times, you can use ctl_bus_lock to acquire the bus to issue a sequence of transactions to the bus that cannot be interrupted by another task. See Also ctl_bus_unlock, ctl_bus_lock_ex 19

20 ctl_bus_lock_ex unsigned ctl_bus_lock_ex(ctl_parallel_bus_t *self, CTL_TIMEOUT_t type, CTL_TIME_t time); ctl_bus_lock_ex acquires the bus lock mutex of the bus self using the timeout specified with type and time. If there is no mutex associated with the bus self, ctl_bus_lock_ex returns immediately indicating success. ctl_bus_lock_ex returns a non-zero value if the mutex is acquired within the timeout specification and zero if it is not. All successful locks of the bus by ctl_bus_lock_ex must be paired with a call to ctl_bus_unlock to release the lock. See Also ctl_bus_unlock_bus, ctl_bus_lock 20

21 ctl_bus_read CTL_STATUS_t ctl_bus_read(ctl_parallel_bus_t *self); ctl_bus_read reads the state of the bus self. Note that reading bits configured as output is highly device dependent and the effect of doing so is not specified by this interface. Thread Safety ctl_bus_read is thread-safe if a mutex is associated with the bus self. 21

22 ctl_bus_read_bit CTL_STATUS_t ctl_bus_read_bit(ctl_parallel_bus_t *self, unsigned bit); ctl_bus_read_bit reads bit number bit from the bus self. Return Value ctl_bus_read_bit returns an extended status code: 0 if the port bit is low, 1 if the port bit is high, and a negative value indicating an error. Thread Safety ctl_bus_read_bit is thread-safe if a mutex is associated with the bus self. 22

23 ctl_bus_set_direction CTL_STATUS_t ctl_bus_set_direction(ctl_parallel_bus_t *self, unsigned direction); ctl_bus_set_direction configures the entire bus for input mode or output mode. A bit set to one in direction sets the corresponding bus bit to input mode, and a bit set to zero in direction sets the corresponding bus bit to output mode. The state of the bus outputs corresponding to direction is indeterminate after setting the bus direction. Return Value ctl_bus_set_direction returns a standard status code. Thread Safety ctl_bus_set_direction is thread-safe if a mutex is associated with the bus self. 23

24 ctl_bus_set_input_mode CTL_STATUS_t ctl_bus_set_input_mode(ctl_parallel_bus_t *self, unsigned mask); ctl_bus_set_input_mode sets all corresponding one-bits in mask to input mode for the bus self. If a bit is zero in mask, the input-output direction of that bit is unchanged. Return Value ctl_bus_set_input_mode returns a standard status code. Thread Safety ctl_bus_set_input_mode is thread-safe if a mutex is associated with the bus self. 24

25 ctl_bus_set_output_mode CTL_STATUS_t ctl_bus_set_output_mode(ctl_parallel_bus_t *self, unsigned mask); ctl_bus_set_output_mode sets all corresponding one-bits in mask to output mode for the bus self. If a bit is zero in mask, the input-output direction of that bit is unchanged. The state of bus outputs for bits that are changed from input mode to output mode is undefined after setting the bus direction. Return Value ctl_bus_set_output_mode returns a standard status code. Thread Safety ctl_bus_set_output_mode is thread-safe if a mutex is associated with the bus self. 25

26 ctl_bus_unlock void ctl_bus_unlock(ctl_parallel_bus_t *self); ctl_bus_unlock releases a mutex that was successfully locked using ctl_bus_lock. If there is no mutex associated with the bus self, ctl_bus_unlock returns immediately. It is an error to release a lock that was not acquired successfully. See Also ctl_bus_lock, ctl_bus_lock_ex 26

27 ctl_bus_write CTL_STATUS_t ctl_bus_write(ctl_parallel_bus_t *self, unsigned output); ctl_bus_write writes output to the bus self. Note that writing to output bits configured as inputs is highly device dependent and the effect of doing so is not specified by this interface. Return Value ctl_bus_write returns a standard status code. Thread Safety ctl_bus_write is thread-safe if a mutex is associated with the bus self. 27

28 ctl_bus_write_bit CTL_STATUS_t ctl_bus_write_bit(ctl_parallel_bus_t *self, unsigned bit, unsigned value); ctl_bus_write_bit sets bit bit on the bus self to value. If value is zero, the corresponding bit is cleared to zero and if value is non-zero, the corresponding bit is set to one. Note that writing to output bits configured as inputs is highly device dependent and the effect of doing so is not specified by this interface. Return Value ctl_bus_write_bit returns a standard status code. Thread Safety ctl_bus_write_bit is thread-safe if a mutex is associated with the bus self. 28

29 ctl_bus_write_bits CTL_STATUS_t ctl_bus_write_bits(ctl_parallel_bus_t *self, unsigned mask, unsigned value); ctl_bus_write_bits writes the bits in value to the bus self. Only the bits that are set to one in mask are written to the bus which allows the client to both set and clear bits in a single operation. Return Value ctl_bus_write_bits returns a standard status code. Thread Safety ctl_bus_write_bits is thread-safe if a mutex is associated with the bus self. 29

30 ctl_parallel_bus_initialize void ctl_parallel_bus_initialize(ctl_parallel_bus_t *self); ctl_parallel_bus_initialize initializes the parallel bus self by setting all members to zero. 30

31 <ctl_i2c.h> Overview Abstract I2C bus interface. The types and functions in <ctl_i2c.h> provide a high-level set of services for a bus master to read and write data over one or more I2C buses. Additional features, such as sensor drivers and so on, build upon the services that the I2C interface offers. In addition, all I2C-interfaced devices in the CrossWorks Micro-Graphics Library use the I2C functions here for I/O to LCD and OLED displays. The I2C interface in this library is abstract in the sense that there is no concrete implementation within the library. Rather, implementations of the I2C interface are offered by the many driver packages that you can install as a CrossWorks package. To see examples of this API in use, please install the CrossWorks demonstration package for your particular board and open up its contents in the Project Explorer and take a look around. API Summary Bus CTL_I2C_BUS_t ctl_i2c_lock_bus ctl_i2c_lock_bus_ex ctl_i2c_set_speed ctl_i2c_unlock_bus I/O ctl_i2c_read ctl_i2c_write ctl_i2c_write_read Implementation CTL_I2C_REQUEST_t Constants CTL_I2C_FAST_MODE_PLUS_SPEED CTL_I2C_FAST_MODE_SPEED CTL_I2C_STANDARD_SPEED Abstract I2C bus interface Acquire exclusive bus lock Acquire exclusive bus lock (extended) Set I2C bus speed Release exclusive bus lock Read data from I2C bus Write data to I2C bus Write to then read from I2C bus I/O request block I2C fast-mode+ bus speed I2C fast-mode bus speed I2C standard bus speed 31

32 CTL_I2C_BUS_t typedef struct { CTL_STATUS_t (*transaction)(ctl_i2c_bus_t *, CTL_I2C_REQUEST_t *); CTL_STATUS_t (*set_speed)(ctl_i2c_bus_t *, unsigned); unsigned long speed; CTL_MUTEX_t *mutex; } CTL_I2C_BUS_t; CTL_I2C_BUS_t defines the interface to the device-independent I2C bus driver. Structure transaction Private method to execute an I/O transaction on the I2C bus. set_speed Private method to set the operating speed of the I2C bus. speed Consider this a read-only variable that indicates the selected speed of the I2C bus. mutex If this mutex is non-zero, the I2C functions will acquire the mutex before proceeding to use the I2C bus. For systems that do not share the I2C bus between tasks, the mutex can be zero and it's the user's responsibility to ensure mutual exclusion on the I2C bus. 32

33 CTL_I2C_FAST_MODE_PLUS_SPEED #define CTL_I2C_FAST_MODE_PLUS_SPEED UL // 1 MHz CTL_I2C_FAST_MODE_PLUS_SPEED defines the standard I2C fast-mode+ bus speed of 1 MHz. 33

34 CTL_I2C_FAST_MODE_SPEED #define CTL_I2C_FAST_MODE_SPEED UL // 400 khz CTL_I2C_FAST_MODE_SPEED defines the standard I2C fast-mode bus speed of 400 khz. 34

35 CTL_I2C_REQUEST_t typedef struct { unsigned address; const unsigned char *tx; size_t txlen; unsigned char *rx; size_t rxlen; } CTL_I2C_REQUEST_t; CTL_I2C_REQUEST_t is an I/O request block for an I2C transaction. Clients are not required to use this request block directly from the I2C API, but I2C drivers are required to implement I/O requests according to the block's members: Write-Read request: If both tx and rx are non-null, the I/O request first writes the slave address and data specified by tx and txlen to the bus, issues a repeated start, and reads rxlen bytes from the bus into rx, and finally issues a stop. Write request: If tx is non-null and rx is null, the I/O request writes the slave address and data specified by tx and txlen to the bus, and then issues a stop. Read request: If tx is null and rx is non-null, the I/O request writes the slave address to the bus, reads rxlen bytes from the bus to rx, and issues a stop. Structure address 8-bit address for the I/O request. The low order bit is undefined when passed to the low-level I2C driver, and the I2C driver must correctly set or reset the R/W bit according to the request phase. tx A pointer to the data to write to the bus after the slave address is transmitted. If tx is zero, the driver must skip the write part of the I/O request. txlen The number of bytes to transfer as payload in the write part of the I/O request. rx A pointer to the data to read from the bus after the slave address is transmitted. If rx is zero, the driver must skip the read part of the I/O request. rxlen The number of bytes to transfer as payload in the read part of the I/O request. 35

36 CTL_I2C_STANDARD_SPEED #define CTL_I2C_STANDARD_SPEED UL // 100 khz CTL_I2C_STANDARD_SPEED defines the standard I2C bus speed of 100 khz. 36

37 ctl_i2c_lock_bus void ctl_i2c_lock_bus(ctl_i2c_bus_t *self); ctl_i2c_lock_bus acquires the bus lock mutex of the I2C bus self. If there is no mutex associated with the bus self, ctl_i2c_lock_bus returns immediately indicating success. All locks of the I2C bus by ctl_i2c_lock_bus must be paired with a call to ctl_i2c_unlock_bus to release the lock. Note Because mutexes can be locked multiple times, you can use ctl_i2c_lock_bus to acquire the bus to issue a sequence of I2C transactions to the bus that cannot be interrupted by another task. However, locking the bus this way does not guarantee that other masters, in a multi-master system, are excluded from issuing transactions on the bus. See Also ctl_i2c_unlock_bus, ctl_i2c_lock_bus_ex 37

38 ctl_i2c_lock_bus_ex unsigned ctl_i2c_lock_bus_ex(ctl_i2c_bus_t *self, CTL_TIMEOUT_t type, CTL_TIME_t time); ctl_i2c_lock_bus_ex acquires the bus lock mutex of the I2C bus self using the timeout specified with type and time. If there is no mutex associated with the bus self, ctl_i2c_lock_bus_ex returns immediately indicating success. ctl_i2c_lock_bus_ex returns a non-zero value if the mutex is acquired within the timeout specification and zero if it is not. All successful locks of the I2C bus by ctl_i2c_lock_bus_ex must be paired with a call to ctl_i2c_unlock_bus to release the lock. Note Because mutexes can be locked multiple times, you can use ctl_i2c_lock_bus_ex to acquire the bus to issue a sequence of I2C transactions to the bus that cannot be interrupted by another task. However, locking the bus this way does not guarantee that other masters, in a multi-master system, are excluded from issuing transactions on the bus. See Also ctl_i2c_unlock_bus, ctl_i2c_lock_bus 38

39 ctl_i2c_read CTL_STATUS_t ctl_i2c_read(ctl_i2c_bus_t *self, unsigned address, void *rx, size_t len); ctl_i2c_read locks the I2C bus self using ctl_i2c_lock_bus and proceeds to read len bytes from the device with 8-bit slave address address and writes them to the object pointed to by rx which must be at least len bytes in size. ctl_i2c_read waits unconditionally for the write and read to complete, unlocks the bus using ctl_i2c_unlock_bus, and returns a standard status code. For exact I2C transaction details, see CTL_I2C_REQUEST_t. Thread Safety This function is thread-safe if a mutex is associated with the I2C bus self. See Also CTL_I2C_REQUEST_t. 39

40 ctl_i2c_set_speed CTL_STATUS_t ctl_i2c_set_speed(ctl_i2c_bus_t *self, unsigned long speed); ctl_i2c_set_speed sets the operating speed of the I2C bus self to speed hertz. If the bus does not support the requested speed, the speed closest to, but not exceeding, speed is selected. Return Value ctl_i2c_set_speed returns a standard status code. Thread Safety ctl_i2c_set_speed is thread-safe if a mutex is associated with the I2C bus self. 40

41 ctl_i2c_unlock_bus void ctl_i2c_unlock_bus(ctl_i2c_bus_t *self); ctl_i2c_unlock_bus releases a mutex that was successfully locked using ctl_i2c_lock_bus. If there is no mutex associated with the bus self, ctl_i2c_unlock_bus returns immediately. It is an error to release a lock that was not acquired successfully. See Also ctl_i2c_lock_bus, ctl_i2c_lock_bus_ex 41

42 ctl_i2c_write CTL_STATUS_t ctl_i2c_write(ctl_i2c_bus_t *self, unsigned address, const void *tx, size_t len); ctl_i2c_write locks the I2C bus self using ctl_i2c_lock_bus and proceeds to write the object pointed to by tx with size len bytes to the device with 8-bit slave address address. ctl_i2c_write waits unconditionally for the write and read to complete, unlocks the bus using ctl_i2c_unlock_bus, and returns a standard status code. For exact I2C transaction details, see CTL_I2C_REQUEST_t. See Also CTL_I2C_REQUEST_t. 42

43 ctl_i2c_write_read CTL_STATUS_t ctl_i2c_write_read(ctl_i2c_bus_t *self, unsigned address, const void *tx, size_t txlen, void *rx, size_t rxlen); ctl_i2c_write_read locks the I2C bus self using ctl_i2c_lock_bus and proceeds to write the object pointed to by tx with size txlen bytes to device with 8-bit slave address address. ctl_i2c_write_read then issues a repeated start to the same slave address and reads len bytes from the slave and writes them to the object pointed to by rx which must be at least rxlen bytes in size. ctl_i2c_write_read waits unconditionally for the write and read to complete, unlocks the bus using ctl_i2c_unlock_bus, and returns a standard status code. For exact I2C transaction details, see CTL_I2C_REQUEST_t. Thread Safety This function is thread-safe if a mutex is associated with the I2C bus self. See Also CTL_I2C_REQUEST_t. 43

44 <ctl_spi.h> Overview Abstract SPI bus interface. The types and functions in <ctl_spi.h> provide a high-level set of services for a bus master to read and write data over one or more SPI buses. Additional features, such as sensor drivers and so on, build upon the services that the SPI interface offers. In addition, all SPI-interfaced devices in the CrossWorks Micro-Graphics Library use the SPI functions here for I/O to LCD and OLED display. The SPI interface in this library is abstract in the sense that there is no concrete implementation within the library. Rather, implementations of the SPI interface are offered by the many driver packages that you can install as a CrossWorks package. To see examples of this API in use, please install the CrossWorks demonstration package for your particular board and open up its contents in the Project Explorer and take a look around. API Summary Bus CTL_SPI_BUS_t ctl_spi_attach_device ctl_spi_deselect_device ctl_spi_detach_device ctl_spi_lock_bus ctl_spi_lock_bus_ex ctl_spi_select_device ctl_spi_unlock_bus Device CTL_SPI_DEVICE_t CTL_SPI_MODE_t CTL_SPI_PROTOCOL_t ctl_spi_exchange ctl_spi_get ctl_spi_issue_deselected_clocks ctl_spi_put ctl_spi_put_get ctl_spi_read Abstract SPI bus interface Attach device to SPI bus Deselect a device from SPI bus Detach device from SPI bus Lock SPI bus Lock SPI bus (extended) Select a device onto SPI bus Unlock SPI bus SPI device instance SPI device mode SPI device configuration Exchange data with SPI device Read one frame from SPI device Issue clocks to SPI bus with device deselected Write one frame to SPI device Exchange one frame with SPI device Read from SPI device 44

45 ctl_spi_set_idle ctl_spi_set_mode ctl_spi_set_protocol ctl_spi_set_speed ctl_spi_set_width ctl_spi_write Implementation CTL_SPI_EXCHANGE_FN_t CTL_SPI_SET_PROTOCOL_FN_t Set SPI device idle state Set SPI device mode Set SPI device operating parameters Set SPI device clock speed Set SPI device frame width Write to SPI device Exchange method prototype Set bus protocol prototype 45

46 CTL_SPI_BUS_t typedef struct { CTL_MUTEX_t *mutex; CTL_SPI_SET_PROTOCOL_FN_t set_protocol; CTL_SPI_EXCHANGE_FN_t exchange; CTL_SPI_DEVICE_t * head; CTL_SPI_DEVICE_t * dev; CTL_SPI_PROTOCOL_t protocol; } CTL_SPI_BUS_t; CTL_SPI_BUS_t contains the bus state and methods that implement an SPI bus. Clients that use the SPI bus should consider all data in this structure private. Structure mutex If this mutex is non-zero, the SPI functions will acquire the mutex proceeding to use the SPI bus. For systems that do not share the SPI bus between tasks, the mutex can be zero and it's the user's responsibility to ensure mutual exclusion on the SPI bus. set_protocol Private method to set the SPI bus protocol for a selected device. Client code must not call this method directly. See CTL_SPI_SET_PROTOCOL_FN_t. exchange Private method to exchange data over the SPI bus. Client code must not call this method directly. See CTL_SPI_EXCHANGE_FN_t. head Private member which is the head of the chain of devices attached to this SPI bus. dev Private member that stores the currently-selected device on the SPI bus; if null, no device is selected. protocol Private member that stores the protocol that the SPI bus is currently configured for. 46

47 CTL_SPI_DEVICE_t typedef struct { int addr; void *extra; void (*select)(ctl_spi_device_s *, int); CTL_SPI_DEVICE_s * next; CTL_SPI_PROTOCOL_t protocol; CTL_SPI_BUS_t * bus; } CTL_SPI_DEVICE_t; CTL_SPI_DEVICE_t defines the device selection method and protocol to use when communicating with a device on an SPI bus. Structure addr Client-side data. If you are using a single method to select multiple devices, you can use the addr member of each SPI device structure to distinguish the device. extra Client-side data. You can use this member to point to additional data associated with the SPI device. select Method to select the device. When the API requires a device to become selected, it calls select with the appropriate SPI device instance and state as 0. When a device needs to be deselected, it calls select with the device instance and state non-zero. next Private member that links SPI device instances attached to the same SPI bus. protocol Private member that contains the SPI protocol associated with the device instance. bus Private member that points to the bus the SPI device is attached to. If the device is not attached to a bus, this member is null. 47

48 CTL_SPI_EXCHANGE_FN_t typedef void (*CTL_SPI_EXCHANGE_FN_t)(CTL_SPI_BUS_t *, const void *, void *, size_t); CTL_SPI_EXCHANGE_FN_t is the prototype for the implementation of data exchange on an SPI bus. 48

49 CTL_SPI_MODE_t typedef enum { CTL_SPI_CPOL_0, CTL_SPI_CPOL_1, CTL_SPI_CPHA_0, CTL_SPI_CPHA_1, CTL_SPI_MODE0, CTL_SPI_MODE1, CTL_SPI_MODE2, CTL_SPI_MODE3 } CTL_SPI_MODE_t; CTL_SPI_MODE_t defines the four operating modes of the SPI bus, 0 through 3. 49

50 CTL_SPI_PROTOCOL_t typedef struct { unsigned char mode; unsigned char width; unsigned short idle; unsigned short options; unsigned long speed; } CTL_SPI_PROTOCOL_t; CTL_SPI_PROTOCOL_t defines the protocol that an SPI device is configured for, or the current configuration of the SPI bus. Structure mode Operating mode of the SPI bus, 0 through 3. width Width of one frame over the SPI bus. Some SPI drivers support only fixed frame widths, or a subset of frame widths, so refer to the documentation of your device to determine the supported frame widths. idle Either 0 or 0xffff which indicates the state MOSI is driven to when reading from the SPI bus. Some SPI devices require that MOSI is driven either high or low when reading from the bus. options Additional options private to the SPI driver. Typically this is used for storing DMA configuration. speed The operating speed of the SPI bus or SPI device, in hertz. 50

51 CTL_SPI_SET_PROTOCOL_FN_t typedef CTL_STATUS_t (*CTL_SPI_SET_PROTOCOL_FN_t)(CTL_SPI_BUS_t *); CTL_SPI_SET_PROTOCOL_FN_t is the prototype for setting the SPI bus protocol (phase, polarity, bus speed, idle state) prior to selecting the device. 51

52 ctl_spi_attach_device CTL_STATUS_t ctl_spi_attach_device(ctl_spi_bus_t *self, CTL_SPI_DEVICE_t *dev); ctl_spi_attach_device attaches the device dev to the SPI bus self. It is an error to operate an SPI device using SPI functions without first attaching it to a bus. Thread Safety ctl_spi_attach_device is thread-safe. See Also ctl_spi_detach_device. 52

53 ctl_spi_deselect_device void ctl_spi_deselect_device(ctl_spi_device_t *self); ctl_spi_deselect_device deselects the device self on the bus that it is attached to. To do this, the device's select method is invoked with a non-zero state, and releases the lock on the SPI bus. Deselecting a deselected device acts as a no-operation. 53

54 ctl_spi_detach_device CTL_STATUS_t ctl_spi_detach_device(ctl_spi_device_t *self); ctl_spi_detach_device removes the device self from the bus it's attached to. If the device is already detached this is a no-operation. Thread Safety ctl_spi_detach_device is thread-safe. See Also ctl_spi_attach_device. 54

55 ctl_spi_exchange CTL_STATUS_t ctl_spi_exchange(ctl_spi_device_t *self, const void *tx, void *rx, size_t items); ctl_spi_exchange simultaneously writes to and reads from the SPI device self which must have been selected onto the bus by ctl_spi_select_device. If the selected frame width for the device self is eight bits or narrower, items bytes are written from tx and items bytes are read from the SPI bus to rx. If the transfer width is nine bits or wider then shorts are used rather than bytes. If tx is zero, the set idle-pattern is written to the SPI device (if the the underlying driver supports such a null transfer). Note that some SPI drivers which use DMA may not support null transfers. If rx is zero, data are read from the SPI bus and discarded if the underlying driver supports such a null transfer. Note that some SPI drivers which use DMA may not support null transfers. 55

56 ctl_spi_get CTL_STATUS_t ctl_spi_get(ctl_spi_device_t *self); ctl_spi_get reads a single frame from the SPI device self which must have been previously selected onto the bus by ctl_spi_select_device. The idle value set in the device's protocol is written to the SPI bus when exchanging data with the device. Return Value The value returned is the frame read from the SPI bus; negative values are standard status codes. 56

57 ctl_spi_issue_deselected_clocks CTL_STATUS_t ctl_spi_issue_deselected_clocks(ctl_spi_device_t *self, size_t items); ctl_spi_issue_deselected_clocks locks the SPI bus associated with the device self and sets the bus protocol to communicate with the device. However, the device is not selected onto the bus and remains deselected. ctl_spi_issue_deselected_clocks then issues items frames of clock pulses to the SPI bus, unlocks the SPI bus, and returns. This function is provided primarily for initializing SD and MMC cards into SPI mode. ctl_spi_issue_deselected_clocks returns a standard status code. 57

58 ctl_spi_lock_bus void ctl_spi_lock_bus(ctl_spi_bus_t *self); ctl_spi_lock_bus acquires the bus lock mutex of the SPI bus self. If there is no mutex associated with the bus self, ctl_spi_lock_bus returns immediately. All locks of the SPI bus by ctl_spi_lock_bus must be paired with a call to ctl_spi_unlock_bus to release the lock. Note Because mutexes can be locked multiple times, you can use ctl_spi_lock_bus to ensure exclusive use of the bus in order to issue a sequence sequence of SPI transactions without interruption. See Also ctl_spi_unlock_bus, ctl_spi_lock_bus_ex 58

59 ctl_spi_lock_bus_ex unsigned ctl_spi_lock_bus_ex(ctl_spi_bus_t *self, CTL_TIMEOUT_t type, CTL_TIME_t time); ctl_spi_lock_bus_ex acquires the bus lock mutex of the SPI bus self using the timeout specified with type and time. If there is no mutex associated with the bus self, ctl_spi_lock_bus_ex returns immediately indicating success. ctl_spi_lock_bus_ex returns a non-zero value if the mutex is acquired within the timeout specification and zero if it is not. All successful locks of the SPI bus by ctl_spi_lock_bus_ex must be paired with a call to ctl_spi_unlock_bus to release the lock. Note Because mutexes can be locked multiple times, you can use ctl_spi_lock_bus_ex to ensure exclusive use of the bus in order to issue a sequence sequence of SPI transactions without interruption. See Also ctl_spi_unlock_bus, ctl_spi_lock_bus 59

60 ctl_spi_put CTL_STATUS_t ctl_spi_put(ctl_spi_device_t *self, unsigned u); ctl_spi_put writes the single frame u to the SPI device self which must have been previously selected onto the bus by ctl_spi_select_device. 60

61 ctl_spi_put_get CTL_STATUS_t ctl_spi_put_get(ctl_spi_device_t *self, unsigned u); ctl_spi_put_get writes the single frame u to the SPI device self which must have been previously selected onto the bus by ctl_spi_select_device and returns the data read when shifting the frame out. 61

62 ctl_spi_read CTL_STATUS_t ctl_spi_read(ctl_spi_device_t *self, void *rx, size_t items); ctl_spi_read read data from the SPI device self which must have been selected onto the bus by ctl_spi_select_device. If the selected transfer width for the device dev is eight bits or narrower then items bytes are read from the SPI bus to rx. If the transfer width is nine bits or wider then item shorts are read from from SPI bus and written to rx. If rx is zero, data are read from the SPI bus and discarded if the underlying driver supports such a null transfer. Note that some SPI drivers which use DMA may not support null transfers. 62

63 ctl_spi_select_device CTL_STATUS_t ctl_spi_select_device(ctl_spi_device_t *self); ctl_spi_select_device selects the device self on the bus that it is attached to and locks access to the bus so other devices cannot use the bus. Once the bus is locked, the device's select method is invoked. The device remains selected until ctl_spi_deselect_device deselects the device and releases the lock on the SPI bus. ctl_spi_select_device returns a standard status code indicating the status of setting the device's SPI protocol. 63

64 ctl_spi_set_idle CTL_STATUS_t ctl_spi_set_idle(ctl_spi_device_t *self, int idle); ctl_spi_set_idle sets the SPI bus idle value when reading from the device self to idle. Please refer to ctl_spi_set_protocol for a description of when protocol parameters are validated. ctl_spi_set_idle returns a standard status code. See Also ctl_spi_set_protocol 64

65 ctl_spi_set_mode CTL_STATUS_t ctl_spi_set_mode(ctl_spi_device_t *self, int mode); ctl_spi_set_mode sets the SPI bus mode to use for the device self to mode. Please refer to ctl_spi_set_protocol for a description of when protocol parameters are validated. ctl_spi_set_mode returns a standard status code. See Also ctl_spi_set_protocol 65

66 ctl_spi_set_protocol CTL_STATUS_t ctl_spi_set_protocol(ctl_spi_device_t *self, int mode, int width, unsigned long speed, int idle); ctl_spi_set_protocol sets the SPI parameters parameters for the device self. You can set the operating parameters of a device whether it is attached to an SPI bus or not. ctl_spi_set_protocol returns a standard status code. Protocol parameter validation If the device is already attached to a bus and is selected, ctl_spi_set_protocol will change the operating parameters of the bus immediately. In this case, if the parameters are invalid or cannot be honored by the underlying SPI bus, ctl_spi_set_protocol will return an error indication immediately. If the device is not attached to a bus or is not selected, the parameters are stored and the bus protocol set when the device is selected. In this case, ctl_spi_set_protocol will return a success indication, leaving validation of the parameters to the time when the device is selected onto the bus using ctl_spi_select_device. 66

67 ctl_spi_set_speed CTL_STATUS_t ctl_spi_set_speed(ctl_spi_device_t *self, unsigned long speed); ctl_spi_set_speed sets the SPI bus frequency to use for the device self to speed hertz. Please refer to ctl_spi_set_protocol for a description of when protocol parameters are validated. ctl_spi_set_speed returns a standard status code. See Also ctl_spi_set_protocol 67

68 ctl_spi_set_width CTL_STATUS_t ctl_spi_set_width(ctl_spi_device_t *self, int width); ctl_spi_set_width sets the SPI bus frame width to use for the device self to width. Please refer to ctl_spi_set_protocol for a description of when protocol parameters are validated. ctl_spi_set_width returns a standard status code. See Also ctl_spi_set_protocol 68

69 ctl_spi_unlock_bus void ctl_spi_unlock_bus(ctl_spi_bus_t *self); ctl_spi_unlock_bus unlocks the previously-locked the SPI bus self. 69

70 ctl_spi_write CTL_STATUS_t ctl_spi_write(ctl_spi_device_t *self, const void *tx, size_t items); ctl_spi_write writes data to the SPI device self which must have been previously selected onto the bus by ctl_spi_select_device. If the selected transfer width for the device self is eight bits or narrower then items bytes are written from tx. If the transfer width is wider than eight bits then item shorts are written from tx. If tx is zero, the set idle-pattern is written to the SPI device (if the the underlying driver supports such a null transfer). Note that some SPI drivers which use DMA may not support null transfers. 70

71 <ctl_sensors.h> Overview Interfaces to a variety of common sensor classes. The types and functions in <ctl_sensors.h> provide a high-level set of services for a variety of common sensor classes such as motion sensors, environmental sensors, and so on. Each sensor class is abstracted to the essential set of features that all sensors of that class provide: Accelerometer: measures linear acceleration in up to three axes, with the abstract interface CTL_ACCELEROMETER_t. Gyroscope: measures rotation rate in up to three axes with the abstract interface CTL_GYROSCOPE_t. Magnetometer: measures magnetic field strength in up to three axes, with the abstract interface CTL_MAGNETOMETER_t. Pressure sensor: measures barometric air pressure, with the abstract interface CTL_PRESSURE_SENSOR_t. Temperature sensor: measures temperature, with the abstract interface CTL_TEMPERATURE_SENSOR_t. Light sensor: measures ambient light level, with the abstract interface CTL_LIGHT_SENSOR_t. Humidity sensor: measures relative humidity and, optionally, temperature, with the abstract interface CTL_HUMIDITY_SENSOR_t. The appropriate interface is initialized by calling the device-specific initialization code, for a particular sensor, in the sensor library. For instance, to initialize an accelerometer interface that uses an ADXL345 acceleration sensor, you would call adxl345_initialize_i2c. Once initialized, you can use the accelerometer-related functions in your own code. API Summary Accelerometer CTL_ACCELEROMETER_t ctl_accelerometer_measure ctl_accelerometer_set_bandwidth ctl_accelerometer_set_range Gyroscope CTL_GYROSCOPE_t ctl_gyroscope_measure ctl_gyroscope_set_bandwidth ctl_gyroscope_set_range An abstract accelerometer Sample accelerometer axes Set accelerometer bandwidth Set accelerometer range An abstract gyroscope Sample gyroscope axes Set gyroscope bandwidth Set gyroscope range 71

72 Magnetometer CTL_MAGNETOMETER_t ctl_magnetometer_measure ctl_magnetometer_set_bandwidth IMU CTL_IMU_t Temperature CTL_TEMPERATURE_SENSOR_t ctl_temperature_sensor_measure ctl_temperature_sensor_set_resolution Pressure Light Humidity CTL_HUMIDITY_SENSOR_t ctl_humidity_sensor_measure Utility CTL_AXIS_TRANSFORMATION ctl_forward_transform_axes ctl_generate_axis_transform Pressure CTL_PRESSURE_SENSOR_t ctl_pressure_sensor_measure Light CTL_LIGHT_SENSOR_t ctl_light_sensor_measure An abstract magnetometer Sample magnetometer axes Set magnetometer bandwidth An abstract IMU sensor collection An abstract temperature sensor Sample temperature sensor Set temperature sensor resolution An abstract humidity sensor Sample relative humidity Single axis transformation Apply axis transformation Generate an axis transform from components An abstract pressure sensor Sample barometric pressure An abstract light sensor Sample ambient light level 72

73 CTL_ACCELEROMETER_t typedef struct { CTL_TRANSPORT_t transport; CTL_STATUS_t (*measure)(ctl_accelerometer_s *, float *); CTL_STATUS_t (*set_range)(ctl_accelerometer_s *, int); CTL_STATUS_t (*set_bandwidth)(ctl_accelerometer_s *, float); float bias[]; float gain[]; int range; float bandwidth; void *extra; unsigned mode; } CTL_ACCELEROMETER_t; CTL_ACCELEROMETER_t is an abstract accelerometer interface that provides clients with a means to set the range and bandwidth of the accelerometer and to sample acceleration in up to three axes. Structure transport The underlying transport for the accelerometer which provides, typically, an I2C or SPI connection to the device and a means to read one or more registers from the device. bias The zero offset for the x, y, and z axes, in g. Client software may alter these to provide more accurate calibration of the accelerometer. gain The gain for the x, y, and z axes, in g per count. Client software may alter these to provide more accurate calibration of the accelerometer. range Current range selected for the accelerometer, in g, and is read only. bandwidth Current bandwidth selected for the accelerometer, in hertz, and is read only. extra Client-side data. You can use this to store additional information relating to the accelerometer instance. mode Private working storage for the driver. measure Method to sample the x, y, and z axes of the accelerometer. 73

74 set_range Method to set the range of the accelerometer. set_bandwidth Method to set the bandwidth of the accelerometer. 74

75 CTL_AXIS_TRANSFORMATION typedef enum { AXIS_UNCHANGED, AXIS_POSITIVE_X, AXIS_POSITIVE_Y, AXIS_POSITIVE_Z, AXIS_NEGATED, AXIS_NEGATIVE_X, AXIS_NEGATIVE_Y, AXIS_NEGATIVE_Z } CTL_AXIS_TRANSFORMATION; CTL_AXIS_TRANSFORMATION describes the generates an axis transform by specifying the individual transformations for the x, y, and z axes. 75

76 CTL_GYROSCOPE_t typedef struct { CTL_TRANSPORT_t transport; CTL_STATUS_t (*measure)(ctl_gyroscope_s *, float *); CTL_STATUS_t (*set_range)(ctl_gyroscope_s *, int); CTL_STATUS_t (*set_bandwidth)(ctl_gyroscope_s *, float); float gain[]; float bias[]; int range; float bandwidth; void *extra; } CTL_GYROSCOPE_t; CTL_GYROSCOPE_t is an abstract gyroscope interface that provides clients with a means to set the range and bandwidth of the gyroscope and to sample rotation in up to three axes. Structure transport The underlying transport for the gyroscope which provides, typically, an I2C or SPI connection to the device and a means to read one or more registers from the device. bias The zero offset for the x, y, and z axes, in degrees per second. Client software may alter these to provide more accurate calibration of the gyroscope. gain The gain for the x, y, and z axes, in degrees per second per count. Client software may alter these to provide more accurate calibration of the gyroscope. range Current range selected for the gyroscope, in degrees per second, and is read only. bandwidth Current bandwidth selected for the gyroscope, in hertz, and is read only. extra Client-side data. You can use this to store additional information relating to the gyroscope instance. measure Method to sample the x, y, and z axes of the gyroscope. set_range Method to set the range of the gyroscope. 76