Skip to content

Commit cb3a65b

Browse files
ptr814ptr814
committed
Low power application code
1 parent a0c053a commit cb3a65b

30 files changed

+1294
-3589
lines changed

‎LICENSE

Lines changed: 18 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,18 @@
1-
/*
2-
*****************************************************************************
3-
* Copyright by ams OSRAM AG *
4-
* All rights are reserved. *
5-
* *
6-
* IMPORTANT - PLEASE READ CAREFULLY BEFORE COPYING, INSTALLING OR USING *
7-
* THE SOFTWARE. *
8-
* *
9-
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS *
10-
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT *
11-
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS *
12-
* FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT *
13-
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, *
14-
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT *
15-
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, *
16-
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY *
17-
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT *
18-
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE *
19-
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. *
20-
*****************************************************************************
21-
*/
1+
Copyright 2024 ams-OSRAM AG
2+
3+
Permission is hereby granted, free of charge, to any person obtaining a copy of
4+
this software and associated documentation files (the “Software”), to deal in
5+
the Software without restriction, including without limitation the rights to
6+
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
7+
of the Software, and to permit persons to whom the Software is furnished to do
8+
so, subject to the following conditions:
9+
10+
The above copyright notice and this permission notice shall be included in all
11+
copies or substantial portions of the Software.
12+
13+
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
17+
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
18+
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.md

Lines changed: 75 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# TMF8806 (Time-of-flight) Arduino Uno driver
1+
# TMF8806 (Time-of-flight) Low-Power Arduino Uno application
22

3-
This is a simple universal driver to show the capabilies of the time-of-flight device TMF8806.
3+
This is a low-power example which shows how to use the TMF8806 in applications that are battery powered.
44

55
## Requirements
66

@@ -12,159 +12,102 @@ This is a simple universal driver to show the capabilies of the time-of-flight d
1212

1313
## Files
1414

15-
The arduino project in the folder: **tmf8806_app** is a very simple single character command line interpreter listening/printing on UART
16-
It contains the following files:
15+
The arduino project consists of the following files:
1716

18-
- **tmf8806_app.ino** - the arduino specific wrapper for the application
19-
- **tmf8806_app.h** and **tmf8806_app.cpp** - the TMF8806 command line application
20-
- **tmf8806.h** and **tmf8806.cpp** - the TMF8806 driver
21-
- **tmf8806_shim.h** and **tmf8806_shim.cpp** - a shim to abstract the arduino specific I2C, UART and GPIO functions
22-
- **tmf8806_image.h** and **tmf8806_image.c** - the TMF8806 firmware that is downloaded by the driver as a c-struct
17+
- **tmf8806_low_power.ino** - the arduino specific wrapper for the application
18+
- **tmf8806_app.h** and **tmf8806_app.c** - the TMF8806 low-power application itself
19+
- **tmf8806.h** and **tmf8806.c** - the TMF8806 driver
20+
- **tmf8806_shim.h** and **tmf8806_shim.cpp** - a shim to abstract the arduino specific I2C, UART, GPIO and low-power functions
21+
For the Arduino this needs to be a c++ file. However the shim layer for other platforms could also be a plain C file.
2322

24-
You can use application interrupt driven. For this you need to set the following define to 1: **USE_INTERRUPT_TO_TRIGGER_READ**
2523

26-
### Porting to another MCU
24+
## Configuration
2725

28-
To port the driver and application to another platform you need to adapt the following files:
29-
- **tmf8806_a.ino** - the arduino specific wrapper for the application, replace this with the requirements for your selected platform
30-
- **tmf8806_shim.h** and **tmf8806_shim.cpp** - a shim to abstract the arduino specific I2C, UART and GPIO functions
31-
32-
## UART and command line interpreter
33-
34-
The project listens and talks on the UART. Baud rate is 115200, 8-bit, no parity, 1 stop bit.
35-
36-
The command line interpreter uses single characters followed by ENTER as input commands.
37-
For interfacing with a zeromq server the command line interpreter also supports complex command strings with binary payload.
38-
39-
UART commands (single character)
40-
41-
- a ... dump registers
42-
- c ... toggle configuration
43-
- d ... disable device
44-
- e ... enable device
45-
- f ... factory calibration
46-
- h ... help
47-
- i ... I2C address change
48-
- m ... start measure
49-
- p ... power down
50-
- s ... stop measure
51-
- t ... switch persistence and thresholds
52-
- w ... wakeup
53-
- x ... clock correction on/off
54-
- z ... histogram dump
55-
- + ... log level+
56-
- - ... log level-
57-
58-
UART commands (binary payload)
59-
60-
- b\x30<tmf8806FactoryCalibData data> .. set arbitrary factory calibration data
61-
- b\x31<tmf8806MeasureCmd data> .. set arbitrary configuration
62-
- b\x32<pers,loThres,hiThres> .. set arbitrary persistence / threshold
63-
64-
## Command line interpreter application
65-
66-
The command line interpreter application mimics a simple host application. It allows the user to switch between 2 pre-defined configurations:
67-
68-
- Configuration 0: Period 33 ms, KiloIterations = 400
69-
- Configuration 1: single shot mode, KiloIterations = 100
70-
71-
You can modify the configurations (e.g. choose different period or KiloIterations) in the application source file, recompile and download your own configuration application to the Arduino.
72-
73-
## Examples
26+
The low power example is written with compile-time configuration. The compile time configuration can be changed by modifying the
27+
following defines in the file **tmf8806_app.h**:
7428

75-
### Power up device
29+
- **KILO_ITERATIONS** defines the number of integrations. The range is 10 - 4000, which is internally multiplied by 1000 (as these
30+
are kilo-iterations).
31+
- **PERIOD_NO_OBJECT_IN_MS** defines the interval with which single shot measurements are executed when no object is detected in
32+
the specified distance range (see parameters LOW_THESHOLD_MM and HIGH_THRESHOLD_MM). Note that the arduino uno uses for this
33+
purpose the watchdog timer which is limited in the available timing configuration to: 16ms, 32ms, 64ms, 128ms, 256ms 512ms, 512ms
34+
1024ms 2048ms 4096ms and 8192ms. The application will use an interval that is equal or bigger than the given PERIOD_NO_OBJECT_IN_MS. If it the number is greater than 8192 it will automatically be set to 8192.
35+
- **PERIOD_OBJECT_IN_MS** defines the interval with which single shot measurements are executed when an object is in the specified range.
36+
Same restrictions as for PERIOD_NO_OBJECT_IN_MS apply for this constant.
37+
- **PERSISTENCE** - defines many consecutive times any object has to be in the specified range before a "object-in-range" is signalled
38+
(via UART and/or GPIO and/or LED). The value 0 has the special meaning that every object (including out-of-range objects) are reported.
39+
E.g. a value of 3 means that there have to be 3 measurements in a row with: HIGH_THRESHOLD_MM >= object distance >= LOW_THRESHOLD_MM.
40+
- **LOW_THRESHOLD_MM** - defines the minimum distance an object must have to be considered in range
41+
- **HIGH_THRESHOLD_MM** - defines the minimum distance an object must have to be considered in range
7642

77-
Before the device can be used the host must power the device. The arduino uno setup function will pull the enable line to the TMF8806 low. I.e. the TMF8806 will be powered down.
43+
- **OUTPUT_ON_UART** - if set to 1 results will be published on UART. If set to 0 the code that writes to the UART will be removed from the binary image. The configuration of the UART is 115200 baud, 8-bit data, 1 stop bit, no parity bit.
44+
- **OUTPUT_ON_LED** - if set to 1 and if an object is for at least PERSISTENCE measurements in a series in range the arduino built-in led will be on, else the led will be off. Note that the bootloader of the arduino also uses the built-in led during boot process so it will aso be on during booting. If set to 0 the code controlling the built-in led is removed from the binary image and the led will be in the state defined by the arduino uno bootloader.
45+
- **OUTPUT_ON_GPIO** - if set to 1 and if an object is for at least PERSISTENCE measurements in a series in range the gpio defined in file tmf8806_shim.h as **RESULT_PIN** will be high, else the pin will be low. If set to 0 the code controlling the gpio pin is removed from the binary image and the pin will be in the default state defined by the arduino uno.
7846

79-
Enter the character
8047

81-
- e
48+
**Note:** The total integration time is the maximum of these 2 values:
49+
1. Integration time defined through KILO_ITERATIONS plus data processing time and algorithm publishing time
50+
2. Period of measurements
51+
E.g. if the period is shorter than the integration time than the measurements will happen with the period of the integration time.
8252

83-
followed by ENTER to enable the device. If necessary the driver will automatically download the the firmware patch file to the TMF8806 RAM. The arduino uno will publish the FW version in the terminal:
53+
## Application control flow
8454

85-
e.g. version 192.4.11.0
55+
The application itself has 2 functions that are called from the arduino framework (see **tmf8806_low_power.ino** file):
56+
1. void setup( ) - is called only once after power up of the arduino
57+
2. void loop( ) - is called periodically while the arduino is running
8658

87-
### Power up device and do measurements
88-
89-
Type the following commands on UART:
90-
91-
- e
92-
- m
93-
94-
The header for the results looks like this:
95-
\#Obj,i2c_slave_address,result_number,reliability,measured_distance,corrected_distance,sys_clock,temperature,reference_hits,object_hits,crosstalk
96-
97-
You will see measurement result records on the UART for the default configuration.
98-
99-
\#Obj,65,165,63,295,295,735639833,27,69216,27384,829
100-
\#Obj,65,166,63,295,295,735796255,27,69243,27459,830
101-
\#Obj,65,167,63,294,294,735951813,27,69362,27297,799
102-
103-
# Factory calibration
104-
105-
Factory calibration must be done for each device.
106-
107-
The simplest way is to do a live factory calibration. I.e. do the following steps:
108-
1. Connect your Arduino Uno and tmf8806 to the PC via USB
109-
2. Start a terminal program
110-
3. Configure and connect the terminal program to the arduino uno
111-
4. Make sure you have a cover glass on top of the TMF8806. This is needed for the crosstalk.
112-
5. Make sure there is no object in front of the TMF8806 within 40 cm.
113-
6. Enter the following commands in your terminal console:
114-
- e
115-
- f
116-
7. The application reports the calibration data: e.g. #Cal,2,0,0,A,B0,BE,BD,7C,F5,F0,F3,F7,7,4
117-
8. If the application does not send the calibration data the calibration has failed. Check your cover glass and check if there is no object (within 40cm) in the field-of-view of the sensor.
118-
119-
## Crosstalk readout
120-
121-
The application reports the crosstalk with each measurement result. E.g.:
59+
To have a portable application the actual code of the **setup** function and the **loop** function is implemented in the file **tmf8806_app.c**.
60+
The flow chart below shows the control flow of the application.
61+
![image](./pictures/low_power_flowchart.png)
62+
12263

123-
\#Obj,65,167,63,294,294,735951813,27,69362,27297,799
12464

125-
The crosstalk is the last field in the line.
65+
## Porting to another MCU
12666

127-
## I2C slave address changing
67+
To port the driver and application to another platform you need to adapt the following files:
68+
- **tmf8806_a.ino** - the arduino specific wrapper for the application, replace this with the requirements for your selected platform
69+
- **tmf8806_shim.h** and **tmf8806_shim.cpp** - a shim to abstract the arduino specific functions
12870

129-
Send the command "i" to the application to change the sensor I2C address. The application will report the new I2C address. E.g.: Addr=0x42
71+
The shim layer contains all arduino uno specific code and defines like e.g. which pin is used for the ENABLE line of the TMF8806, which pin is used for the INTERRUPT line of the TMF8806, which pin shall be used to signal that an object is in range.
72+
The arduino uno is an 8-bit processor which has some limitation on the I2C. the 2 most stringent are
73+
- maximum I2C frequency is 400KHz
74+
- maximum I2C block transfer size is 32 bytes (including the register address byte)
13075

131-
# Histogram dumping
13276

133-
The device can also dump histograms. The order the Arduino Uno driver reports these histograms is exactly the same as the TMF8806 reports them on I2C.
77+
## Measurement result
13478

135-
There are five different types of histograms available
79+
### Current measurement
80+
Using default settings, the measured average current is only 26 uA.
13681

137-
- electrical calibration histograms (ID=1)
138-
- proximity histograms (ID=2)
139-
- distance histograms (ID=4)
140-
- pileup-corrected distance histograms (ID=8)
141-
- summed histogram (ID=16)
82+
Power consumption profile:<br>
83+
![image](./pictures/power_consumption.png)
84+
<br> x-axis: 200ms/div
85+
<br> y-axis: 10mA/div
14286

143-
Type "z" and ENTER until you have the desired value for histogram dumping. E.g if the application sends:
87+
Power consumption profile zoomed in:<br>
88+
![image](./pictures/power_consumption_zoom.png)
89+
<br> x-axis: 10ms/div
90+
<br> y-axis: 10mA/div
14491

145-
Histogram is 4
92+
### Check functionality using default settings
93+
Setup with no object in front. Expected period in ms: 1024
94+
<br> Measured INT Line: 1030 ms<br>
95+
![image](./pictures/eval_int_no_object.png)
14696

147-
distance histograms are configured for dumping. The application dumps ALL histograms if:
97+
Setup with object in front. Expected period in ms: 128
98+
<br> Measured INT Line: 130 ms<br>
99+
![image](./pictures/eval_int_object.png)
148100

149-
Histogram is 31
101+
Persistence: 3
102+
<br>Low Threshold: 50
103+
<br>High Threshold: 200<br>
104+
![image](./pictures/eval_persistence.png)
150105

151-
For all histograms, the first number after the marker (e.g. #TG7) will give the channel this histogram contains.
106+
Output on UART: ON<br>
107+
![image](./pictures/eval_uart.png)
152108

153-
There are always 10 histograms reported.
109+
Output on LED: ON<br>
110+
![image](./pictures/eval_led.png)
154111

155-
- Number 0 == TDC0, Channel0
156-
- Number 1 == TDC0, Channel1
157-
- ...
158-
- Number 9 == TDC4, Channel0
159-
- Number 10 == TDC0, Channel1
160-
161-
The header for the raw histograms looks like this:
162-
\#<histogram_type>,bin_0,bin_1,...,bin_127
163-
164-
Line Tag | Histogram Type
165-
----------|-----------------------
166-
\#CI | electrical calibration
167-
\#PT | proximity
168-
\#TG | distance
169-
\#TGPUC | pileup-corrected distance
170-
\#SUM | summed
112+
Output on GPIO: ON<br>
113+
![image](./pictures/eval_GPIO.png)

‎how_to_generate_image_from_hex/generate_tof_image.bat

Lines changed: 0 additions & 1 deletion
This file was deleted.

0 commit comments

Comments
 (0)