Chirp SonicLib  2.1.0
ch_driver.h
Go to the documentation of this file.
1 
18 /*
19  * Copyright © 2016-2020, Chirp Microsystems. All rights reserved.
20  *
21  * Chirp Microsystems CONFIDENTIAL
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
24  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
25  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
26  * DISCLAIMED. IN NO EVENT SHALL CHIRP MICROSYSTEMS BE LIABLE FOR ANY
27  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
28  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
29  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
30  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
31  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
32  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33  *
34  * You can contact the authors of this program by email at support@chirpmicro.com
35  * or by mail at 2560 Ninth Street, Suite 220, Berkeley, CA 94710.
36  */
37 
38 #ifndef CH_DRIVER_H_
39 #define CH_DRIVER_H_
40 
41 //#define CHDRV_DEBUG
42 
43 #include "chirp_board_config.h"
44 #include "soniclib.h"
45 
46 #include <stdint.h>
47 #include <stdlib.h>
48 #include <math.h>
49 #include <string.h>
50 #ifdef CHDRV_DEBUG
51 #include <stdio.h>
52 #endif
53 
54 
55 #define CHDRV_I2C_MAX_WRITE_BYTES 256
57 #define CHDRV_NB_TRANS_TYPE_STD (0)
58 #define CHDRV_NB_TRANS_TYPE_PROG (1)
59 #define CHDRV_NB_TRANS_TYPE_EXTERNAL (2)
61 /* Programming interface register addresses */
62 #define CH_PROG_REG_PING 0x00
63 #define CH_PROG_REG_CPU 0x42
64 #define CH_PROG_REG_STAT 0x43
65 #define CH_PROG_REG_CTL 0x44
66 #define CH_PROG_REG_ADDR 0x05
67 #define CH_PROG_REG_CNT 0x07
68 #define CH_PROG_REG_DATA 0x06
70 #define CH_PROG_SIZEOF(R) ( (R) & 0x40 ? 1 : 2 )
71 
73 #define CH_PROG_XFER_SIZE (256)
75 #define CHDRV_DEBUG_PIN_NUM (0)
78 #define CHDRV_MAX_I2C_QUEUE_LENGTH CHIRP_MAX_NUM_SENSORS
80 #define CHDRV_FREQLOCK_TIMEOUT_MS 100
82 #define CHDRV_BANDWIDTH_INDEX_1 6
83 #define CHDRV_BANDWIDTH_INDEX_2 (CHDRV_BANDWIDTH_INDEX_1 + 1)
86 #define CHDRV_SCALEFACTOR_INDEX 4
88 #define CHDRV_TRIGGER_PULSE_US 5
89 #define CHDRV_DELAY_OVERHEAD_US 12
90 #define CHDRV_PRETRIGGER_DELAY_US 600
94 typedef uint8_t (*chdrv_discovery_hook_t)(ch_dev_t *dev_ptr);
96 
97 
99 typedef struct chdrv_i2c_transaction {
100  uint8_t type;
101  uint8_t rd_wrb;
102  uint8_t xfer_num;
103  uint16_t addr;
104  uint16_t nbytes;
106  uint8_t *databuf;
111 typedef struct chdrv_i2c_queue {
112  uint8_t read_pending;
113  uint8_t running;
114  uint8_t len;
115  uint8_t idx;
135 void chdrv_group_measure_rtc(ch_group_t *grp_ptr);
136 
150 uint32_t chdrv_one_way_range(ch_dev_t *dev_ptr, uint16_t tof, uint16_t tof_sf);
151 
165 uint32_t chdrv_round_trip_range(ch_dev_t *dev_ptr, uint16_t tof, uint16_t tof_sf);
166 
180 int chdrv_group_i2c_queue(ch_group_t *grp_ptr, ch_dev_t *instance, uint8_t rd_wrb, uint8_t type, uint16_t addr, uint16_t nbytes, uint8_t *data);
181 
201 int chdrv_external_i2c_queue(ch_group_t *grp_ptr, ch_dev_t *instance, uint8_t rd_wrb, uint16_t addr,
202  uint16_t nbytes, uint8_t *data);
203 
211 void chdrv_group_i2c_start_nb(ch_group_t *grp_ptr);
212 
222 void chdrv_group_i2c_irq_handler(ch_group_t *grp_ptr, uint8_t i2c_bus_index);
223 
235 int chdrv_wait_for_lock(ch_dev_t *dev_ptr, uint16_t timeout_ms );
236 
250 
262 int chdrv_group_hw_trigger(ch_group_t *grp_ptr);
263 
279 int chdrv_hw_trigger(ch_dev_t *dev_ptr);
280 
295 int chdrv_prog_ping(ch_dev_t *dev_ptr);
296 
313 int chdrv_detect_and_program(ch_dev_t *dev_ptr);
314 
333 
350 int chdrv_init(ch_dev_t *dev_ptr, uint8_t i2c_addr, uint8_t io_index, uint8_t i2c_bus_index,
351  uint16_t part_number);
352 
362 int chdrv_group_prepare(ch_group_t* grp_ptr);
363 
378 int chdrv_group_start(ch_group_t *grp_ptr);
379 
389 int chdrv_write_byte(ch_dev_t *dev_ptr, uint16_t mem_addr, uint8_t data);
390 
400 int chdrv_write_word(ch_dev_t *dev_ptr, uint16_t mem_addr, uint16_t data);
401 
411 int chdrv_read_byte(ch_dev_t *dev_ptr, uint16_t mem_addr, uint8_t *data);
412 
422 int chdrv_read_word(ch_dev_t *dev_ptr, uint16_t mem_addr, uint16_t * data);
423 
435 int chdrv_burst_read(ch_dev_t *dev_ptr, uint16_t mem_addr, uint8_t *data, uint16_t len);
436 
448 int chdrv_burst_write(ch_dev_t *dev_ptr, uint16_t mem_addr, uint8_t *data, uint8_t len);
449 
460 int chdrv_soft_reset(ch_dev_t *dev_ptr);
461 
471 int chdrv_group_hard_reset(ch_group_t *grp_ptr );
472 
483 int chdrv_group_soft_reset(ch_group_t *grp_ptr );
484 
496 int chdrv_set_idle(ch_dev_t *dev_ptr );
497 
498 
510 int chdrv_prog_write(ch_dev_t *dev_ptr, uint8_t reg_addr, uint16_t data);
511 
524 int chdrv_prog_i2c_write(ch_dev_t *dev_ptr, uint8_t *message, uint16_t len);
525 
538 int chdrv_prog_i2c_read(ch_dev_t *dev_ptr, uint8_t *message, uint16_t len);
539 
553 int chdrv_prog_i2c_read_nb(ch_dev_t *dev_ptr, uint8_t *message, uint16_t len);
554 
568 int chdrv_prog_mem_write(ch_dev_t *dev_ptr, uint16_t addr, uint8_t *message, uint16_t nbytes);
569 
570 
582 void chdrv_discovery_hook_set(ch_group_t *grp_ptr, chdrv_discovery_hook_t hook_func_ptr);
583 
595 void chdrv_pretrigger_delay_set(ch_group_t *grp_ptr, uint16_t delay_us);
596 
597 #endif /* CH_DRIVER_H_ */
int chdrv_group_i2c_queue(ch_group_t *grp_ptr, ch_dev_t *instance, uint8_t rd_wrb, uint8_t type, uint16_t addr, uint16_t nbytes, uint8_t *data)
Add an I2C transaction to the non-blocking queue.
uint8_t xfer_num
Definition: ch_driver.h:105
int chdrv_group_hard_reset(ch_group_t *grp_ptr)
Perform a hard reset on a group of sensors.
int chdrv_external_i2c_queue(ch_group_t *grp_ptr, ch_dev_t *instance, uint8_t rd_wrb, uint16_t addr, uint16_t nbytes, uint8_t *data)
Add an I2C transaction for an external device to the non-blocking queue.
int chdrv_init(ch_dev_t *dev_ptr, uint8_t i2c_addr, uint8_t io_index, uint8_t i2c_bus_index, uint16_t part_number)
Initialize the sensor device configuration.
uint16_t nbytes
Definition: ch_driver.h:107
int chdrv_read_byte(ch_dev_t *dev_ptr, uint16_t mem_addr, uint8_t *data)
Read byte from a sensor application register.
int chdrv_prog_i2c_write(ch_dev_t *dev_ptr, uint8_t *message, uint16_t len)
Write bytes to a sensor device in programming mode.
uint8_t running
Definition: ch_driver.h:116
int chdrv_group_hw_trigger(ch_group_t *grp_ptr)
Start a measurement in hardware triggered mode.
Chirp SonicLib public API and support functions for Chirp ultrasonic sensors.
int chdrv_set_idle(ch_dev_t *dev_ptr)
Put sensor(s) in idle state.
struct chdrv_i2c_transaction chdrv_i2c_transaction_t
I2C transaction control structure.
Chirp sensor device structure.
Definition: soniclib.h:349
int chdrv_soft_reset(ch_dev_t *dev_ptr)
Perform a soft reset on a sensor.
uint32_t chdrv_round_trip_range(ch_dev_t *dev_ptr, uint16_t tof, uint16_t tof_sf)
Convert the sensor register values to a round-trip range using the calibration data in the ch_dev_t s...
int chdrv_write_byte(ch_dev_t *dev_ptr, uint16_t mem_addr, uint8_t data)
Write byte to a sensor application register.
uint8_t type
Definition: ch_driver.h:103
uint8_t read_pending
Definition: ch_driver.h:115
int chdrv_group_wait_for_lock(ch_group_t *grp_ptr)
Wait for all sensors to finish start-up procedure.
int chdrv_hw_trigger(ch_dev_t *dev_ptr)
Start a measurement in hardware triggered mode on one sensor.
uint32_t chdrv_one_way_range(ch_dev_t *dev_ptr, uint16_t tof, uint16_t tof_sf)
Convert the sensor register values to a range using the calibration data in the ch_dev_t struct...
int chdrv_detect_and_program(ch_dev_t *dev_ptr)
Detect, program, and start a sensor.
int chdrv_group_soft_reset(ch_group_t *grp_ptr)
Perform a soft reset on a group of sensors.
void chdrv_pretrigger_delay_set(ch_group_t *grp_ptr, uint16_t delay_us)
Set the pre-trigger delay for rx-only sensors.
int chdrv_prog_i2c_read(ch_dev_t *dev_ptr, uint8_t *message, uint16_t len)
Read bytes from a sensor device in programming mode.
void chdrv_group_i2c_irq_handler(ch_group_t *grp_ptr, uint8_t i2c_bus_index)
Continue a non-blocking readout.
uint8_t idx
Definition: ch_driver.h:118
ch_dev_t * dev_ptr
Definition: ch_driver.h:108
Chirp sensor group configuration structure.
Definition: soniclib.h:329
uint8_t * databuf
Definition: ch_driver.h:109
int chdrv_group_prepare(ch_group_t *grp_ptr)
Initialize data structures and hardware for sensor interaction and reset sensors. ...
int chdrv_group_detect_and_program(ch_group_t *grp_ptr)
Detect, program, and start all sensors in a group.
int chdrv_prog_write(ch_dev_t *dev_ptr, uint8_t reg_addr, uint16_t data)
Write to a sensor programming register.
int chdrv_group_start(ch_group_t *grp_ptr)
Initalize and start a group of sensors.
I2C queue structure, for non-blocking access.
Definition: ch_driver.h:114
I2C transaction control structure.
Definition: ch_driver.h:102
int chdrv_prog_i2c_read_nb(ch_dev_t *dev_ptr, uint8_t *message, uint16_t len)
Read bytes from a sensor device in programming mode, non-blocking.
int chdrv_burst_write(ch_dev_t *dev_ptr, uint16_t mem_addr, uint8_t *data, uint8_t len)
Write multiple bytes to a sensor application register location.
int chdrv_prog_mem_write(ch_dev_t *dev_ptr, uint16_t addr, uint8_t *message, uint16_t nbytes)
Write to sensor memory.
void chdrv_group_measure_rtc(ch_group_t *grp_ptr)
Calibrate the sensor real-time clock against the host microcontroller clock.
void chdrv_discovery_hook_set(ch_group_t *grp_ptr, chdrv_discovery_hook_t hook_func_ptr)
Register a hook routine to be called after device discovery.
void chdrv_group_i2c_start_nb(ch_group_t *grp_ptr)
Start a non-blocking sensor readout.
int chdrv_write_word(ch_dev_t *dev_ptr, uint16_t mem_addr, uint16_t data)
Write 16 bits to a sensor application register.
uint8_t len
Definition: ch_driver.h:117
chdrv_i2c_transaction_t transaction[CHDRV_MAX_I2C_QUEUE_LENGTH]
Definition: ch_driver.h:119
uint8_t rd_wrb
Definition: ch_driver.h:104
#define CHDRV_MAX_I2C_QUEUE_LENGTH
Definition: ch_driver.h:79
int chdrv_burst_read(ch_dev_t *dev_ptr, uint16_t mem_addr, uint8_t *data, uint16_t len)
Read multiple bytes from a sensor application register location.
int chdrv_read_word(ch_dev_t *dev_ptr, uint16_t mem_addr, uint16_t *data)
Read 16 bits from a sensor application register.
int chdrv_prog_ping(ch_dev_t *dev_ptr)
Detect a connected sensor.
int chdrv_wait_for_lock(ch_dev_t *dev_ptr, uint16_t timeout_ms)
Wait for an individual sensor to finish start-up procedure.
uint8_t(* chdrv_discovery_hook_t)(ch_dev_t *dev_ptr)
Hook routine pointer typedefs.
Definition: ch_driver.h:98
struct chdrv_i2c_queue chdrv_i2c_queue_t
I2C queue structure, for non-blocking access.
uint16_t addr
Definition: ch_driver.h:106