Skip to content

Commit 2199c24

Browse files
gigapodgigapod
committed
clean device docs; add setup docs
1 parent 0eea010 commit 2199c24

File tree

2 files changed

+141
-17
lines changed

2 files changed

+141
-17
lines changed

‎docs/api_device.md‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ bool getApplicationVersion(char *Version, uint8_t vlen)
7575
Returns the unique ID of the connected TMF882X.
7676

7777
!!! note
78-
This method uses a ID structure as defined by the AMS TMF882X SDK to
78+
This method uses an ID structure as defined by the AMS TMF882X SDK to
7979
store the ID value.
8080

8181
```C++
@@ -166,4 +166,20 @@ void setOutputDevice(Stream& theStream)
166166
167167
| Parameter | Type | Description |
168168
| :------------ | :---------- | :---------------------------------------------- |
169-
| `theStream` | `Stream` | The output stream device - normally a Serial port. |
169+
| `theStream` | `Stream` | The output stream device - normally a Serial port. |
170+
171+
### getTMF882XContext()
172+
Returns the context structure used by this library when accessing the underlying TMF882X SDK.
173+
174+
With this structure, users of this library can make direct calls to the interface functions of the TMF882X SDK.
175+
176+
!!! warning
177+
Calling the TMF882X SDK functions directly could impact the operation of this library. Use this option with caution.
178+
179+
```C++
180+
tmf882x_tof &getTMF882XContext(void)
181+
```
182+
183+
| Parameter | Type | Description |
184+
| :------------ | :---------- | :---------------------------------------------- |
185+
| return value | `tmf882x_tof` | The TMF882X Context being used by this library. |

‎docs/api_setup.md‎

Lines changed: 123 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,150 @@
1-
# Arduino Print
1+
# Device Setup
22

3-
Methods used to support Arduino Print functionality.
3+
Methods used to setup and configure the device before taking data samples.
44

5-
### setCursor()
5+
## Configuration
66

7-
This method is called set the "cursor" position in the device. The library supports the Arduino `Print` interface, enabling the use of a `print()` and `println()` methods. The set cursor position defines where to start text output for this functionality.
7+
### getTMF882XConfig()
8+
9+
The underlying TMF882X SDK uses a "configuration structure" to read and modify the configuration of the connected device. This method retrieves the current configuration of the device.
10+
11+
When changing a value of the configuration, the following steps are taken:
12+
* Retrieve the current configuration using `getTMF882XConfig()`
13+
* Change the value in the configuration structure
14+
* Updating the device configuration using the method `setTMF882XConfig()`
15+
16+
The configuration is transferred as a structure of type `struct tmf882x_mode_app_config`. This structure is defined by the TMF882X SDK, and contains the following fields:
17+
18+
| Type | Struct Field | Description |
19+
| :--- | :--- | :--- |
20+
| uint16_t | report_period_ms | Result reporting period in milliseconds |
21+
| uint16_t | kilo_iterations | Iterations * 1024 for measurements |
22+
| uint16_t | low_threshold | Low distance threshold setting triggering interrupts |
23+
| uint16_t | high_threshold | High distance threshold setting triggering interrupts |
24+
| uint32_t | zone_mask | Zone mask for disabling interrupts for certain channels |
25+
| uint8_t | persistence | Persistence setting for generating interrupts |
26+
| uint8_t | confidence_threshold | Confidence threshold for generating interrupts |
27+
| uint8_t | gpio_0 | GPIO_0 config settings |
28+
| uint8_t | gpio_1 | GPIO_1 config settings |
29+
| uint8_t | power_cfg | Power configuration settings |
30+
| uint8_t | spad_map_id | Spad map identifier |
31+
| uint32_t | alg_setting | Algorithm setting configuration |
32+
| uint8_t | histogram_dump | Histogram dump configuration |
33+
| uint8_t | spread_spectrum | Spread Spectrum configuration |
34+
| uint8_t | i2c_slave_addr | I2C slave address configuration |
35+
| uint16_t | oscillator_trim | Sensor Oscillator trim value |
36+
37+
The details and specific values for the above fields are detailed in the TMF882X datasheet.
38+
39+
```c++
40+
bool getTMF882XConfig(struct tmf882x_mode_app_config tofConfig)
41+
```
42+
43+
| Parameter | Type | Description |
44+
| :--- | :--- | :--- |
45+
| tofConfig | `struct tmf882x_mode_app_config` | A configuration structure that the current configuration data is copied to|
46+
| return value| `bool` | `true` on success, `false` on an error |
47+
48+
49+
### setTMF882XConfig()
50+
51+
Call this method to set the current configuration page in the connected TMF882X device. A `tmf882x_mode_app_config` structure with the desired values is passed into this method. Details of the structure fields are listed in the description of the `getTMF882XConfig()` method.
52+
53+
When changing a value of the configuration, the following steps are taken:
54+
* Retrieve the current configuration using `getTMF882XConfig()`
55+
* Change the value in the configuration structure
56+
* Updating the device configuration using the method `setTMF882XConfig()`
857
958
```c++
10-
void setCursor(uint8_t x, uint8_t y)
59+
bool setTMF882XConfig(struct tmf882x_mode_app_config tofConfig)
1160
```
1261

1362
| Parameter | Type | Description |
1463
| :--- | :--- | :--- |
15-
| x | `uint8_t` | The X coordinate of the cursor|
16-
| y | `uint8_t` | The Y coordinate of the cursor|
64+
| tofConfig | `struct tmf882x_mode_app_config` | A configuration structure that has the desired settings for the device|
65+
| return value| `bool` | `true` on success, `false` on an error |
66+
67+
## SPAD Settings
68+
1769

18-
### setColor()
70+
### getCurrentSPADMap()
1971

20-
This method is called to set the current color of the system. This is used by the Arduino `Print` interface functionality
72+
This method returns the ID of the current SPAD Map in use on the device. The TMF882X uses a _SPAD Map_ to control the viewing geometry of the sample data retrieved from the sensor. Consult the TMF882X datasheet for SPAD Map details as available ID values.
73+
74+
```c++
75+
uint8_t getCurrentSPADMap(void)
76+
```
77+
78+
| Parameter | Type | Description |
79+
| :--- | :--- | :--- |
80+
| return value| `uint8_t` | `0` on error, otherwise the ID of the SPAD Map|
81+
82+
### setCurrentSPADMap()
83+
84+
This method sets the current SPAD map in the connected device. The SPAD Map is specified by its ID. Available SPAD Maps and their associated IDs are listed in the TMF882X datasheet.
85+
86+
```c++
87+
bool setCurrentSPADMap(uint8_t idSPAD)
88+
```
89+
90+
| Parameter | Type | Description |
91+
| :--- | :--- | :--- |
92+
| idSPAD| `uint8_t` | The ID of the SPAD to make current on the device |
93+
| return value| `bool` | `true` on success, `false` on an error |
94+
95+
### getSPADConfig()
96+
97+
Retrieve the current SPAD configuration from the connected device. This configuration is returned as a `tmf882x_mode_app_spad_config` structure.
98+
99+
100+
The SPAD configuration structure is defined as follows:
101+
```C++
102+
struct tmf882x_mode_app_spad_config {
103+
struct tmf882x_mode_app_single_spad_config {
104+
int8_t xoff_q1;
105+
int8_t yoff_q1;
106+
uint8_t xsize;
107+
uint8_t ysize;
108+
uint8_t spad_mask[TMF8X2X_COM_MAX_SPAD_SIZE];
109+
uint8_t spad_map[TMF8X2X_COM_MAX_SPAD_SIZE];
110+
} spad_configs[TMF8X2X_MAX_CONFIGURATIONS];
111+
uint32_t num_spad_configs;
112+
};
113+
```
114+
The fields are defined as:
115+
116+
| Type | Struct Field | Description |
117+
| :--- | :--- | :--- |
118+
| int8_t | xoff_q1 | X-direction offset in Q1 format |
119+
| int8_t | yoff_q1 | Y-direction offset in Q1 format |
120+
| uint8_t | xsize | Size of spad map in X-direction |
121+
| uint8_t | ysize | Size of spad map in Y-direction |
122+
| uint8_t | spad_mask | Spad enable mask configuration (1 enable, 0 disable)|
123+
| uint8_t | spad_map | Spad channel mapping for measurement (channels 1 - 9) |
124+
| uint32_t | num_spad_configs | he number of spad configurations |
21125
126+
The details and specific values for the above fields are detailed in the TMF882X datasheet.
22127
23128
```c++
24-
void setColor(uint8_t clr)
129+
bool getSPADConfig(struct tmf882x_mode_app_spad_config tofSpad)
25130
```
26131

27132
| Parameter | Type | Description |
28133
| :--- | :--- | :--- |
29-
| `clr` | `uint8_t` | The color to set. 0 = black, > 0 = white|
134+
| tofSpad| `struct tmf882x_mode_app_spad_config` | Struct to hold the current SPAD configuration values. |
135+
| return value| `bool` | `true` on success, `false` on an error |
30136

31-
### getColor()
137+
### setSPADConfig()
32138

33-
This method is called to get the current color of the system. This is used by the Arduino `Print` interface functionality
139+
Set the current SPAD configuration in the connected device. This configuration is set using a `tmf882x_mode_app_spad_config` structure. This method is used to set custom SPAD Maps in the TMF882X.
34140

141+
See the descriptor of `getSPADConfig()` for details of the `tmf882x_mode_app_spad_config`.
35142

36143
```c++
37-
uint8_t getColor(void)
144+
bool setSPADConfig(struct tmf882x_mode_app_spad_config tofSpad)
38145
```
39146
40147
| Parameter | Type | Description |
41148
| :--- | :--- | :--- |
42-
| return value| `uint8_t` | The current color|
149+
| tofSpad| `struct tmf882x_mode_app_spad_config` | The config values for the on device SPAD settings. |
150+
| return value| `bool` | `true` on success, `false` on an error |

0 commit comments

Comments
 (0)