Skip to content

Commit b0214b7

Browse files
gigapodgigapod
committed
half done with operation api docs
1 parent cb98e5f commit b0214b7

File tree

1 file changed

+194
-15
lines changed

1 file changed

+194
-15
lines changed

‎docs/api_operation.md‎

Lines changed: 194 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,221 @@
1-
# Arduino Print
1+
# Operation
22

3-
Methods used to support Arduino Print functionality.
3+
Methods used to read data from the connected TMF882X device.
44

5-
### setCursor()
5+
## Message Callback Functions
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+
The TMF882X SDK returns data via a message structure passed to a user provided C function. This library allows the user to register callback functions that are called during the measurement operation.
8+
9+
The user has the option to register a generic message callback function, or specific functions based on message type.
10+
11+
### setMessageHandler()
12+
13+
Call this method with a function that is called when any message is sent from the AMS sdk. The function passed into this method can be used to handle all messages instead of using the other handlers for specific message types.
14+
15+
The passed in function should be of type `TMF882XMessageHandler`, which is defined as:
16+
17+
```C++
18+
typedef void (*TMF882XMessageHandler)(struct tmf882x_msg *msg);
19+
```
20+
21+
This function accepts a parameter of type tmf882x_msg, which is defined as:
22+
23+
```C++
24+
struct tmf882x_msg {
25+
union {
26+
struct tmf882x_msg_header hdr;
27+
struct tmf882x_msg_error err_msg;
28+
struct tmf882x_msg_histogram hist_msg;
29+
struct tmf882x_msg_meas_results meas_result_msg;
30+
struct tmf882x_msg_meas_stats meas_stat_msg;
31+
uint8_t msg_buf[TMF882X_MAX_MSG_SIZE];
32+
};
33+
};
34+
```
35+
The type of the message is defined in `msg->hdr.msg_id`, and is one of the following types:
36+
37+
| Type | Description |
38+
| :---- | :---- |
39+
| ID_MEAS_RESULTS | The results of a measurement - `meas_result_msg` is valid. |
40+
| ID_MEAS_STATS | The measurement statistics - `meas_stat_msg` is valid. |
41+
| ID_HISTOGRAM | The histogram of a measurement - `hist_msg` is valid. |
42+
| ID_ERROR | An error occurred - `err_msg` is valid. |
43+
44+
```c++
45+
void setMessageHandler(TMF882XMessageHandler handler)
46+
```
47+
48+
| Parameter | Type | Description |
49+
| :--- | :--- | :--- |
50+
| handler | `TMF882XMessageHandler` | The message handler callback C function |
51+
52+
### setMeasurementHandler()
53+
54+
Call this method with a function that is called when measurement data is sent from the AMS sdk.
55+
56+
The passed in function should be of type `TMF882XMeasurementHandler`, which is defined as:
57+
58+
```C++
59+
typedef void (*TMF882XMeasurementHandler)(struct tmf882x_msg_meas_results *message);
60+
```
61+
62+
This function accepts a parameter of type tmf882x_msg_meas_results, which is defined as:
63+
64+
```C++
65+
struct tmf882x_msg_meas_results {
66+
struct tmf882x_msg_header hdr;
67+
uint32_t result_num; /* increments with every new bunch of results */
68+
uint32_t temperature; /* temperature */
69+
uint32_t ambient_light; /* ambient light level */
70+
uint32_t photon_count; /* photon count */
71+
uint32_t ref_photon_count; /* reference photon count */
72+
uint32_t sys_ticks; /* system ticks */
73+
uint32_t valid_results; /* number of valid results */
74+
uint32_t num_results; /* number of results */
75+
struct tmf882x_meas_result results[TMF882X_MAX_MEAS_RESULTS];
76+
};
77+
```
78+
The fields of the message structure are defined as:
79+
80+
| field | Description |
81+
| :---- | :---- |
82+
| result_num | This is the result number reported by the device. |
83+
| temperature | This is the temperature reported by the device (in Celsius) |
84+
| ambient_light | This is the ambient light level reported by the device |
85+
| photon_count | This is the photon count reported by the device |
86+
| ref_photon_count | This is the reference channel photon count reported by the device |
87+
| sys_ticks | This is the system tick counter (5MHz counter) reported by the device. This is used by the core driver to perform clock compensation correction on the measurement results. |
88+
| valid_results | This is the number of targets reported by the device |
89+
| num_results | This is the number of non-zero targets counted by the core driver |
90+
| results | This is the list of measurement targets @ref struct tmf882x_meas_result |
91+
92+
```c++
93+
void setMeasurementHandler(TMF882XMeasurementHandler handler)
94+
```
95+
96+
| Parameter | Type | Description |
97+
| :--- | :--- | :--- |
98+
| handler | `TMF882XMeasurementHandler` | The message handler callback C function |
99+
100+
### setHistogramHandler()
101+
102+
Call this method with a function that is called when histogram data is sent from the AMS sdk.
103+
104+
The passed in function should be of type `TMF882XHistogramHandler`, which is defined as:
105+
106+
```C++
107+
typedef void (*TMF882XHistogramHandler)(struct tmf882x_msg_histogram * message);
108+
```
109+
110+
This function accepts a parameter of type tmf882x_msg_histogram, which is defined as:
111+
112+
```C++
113+
struct tmf882x_msg_histogram {
114+
struct tmf882x_msg_header hdr;
115+
uint32_t capture_num; /* matches the value of 'result_num' from measure result messages*/
116+
uint32_t sub_capture; /* sub-capture measurement nubmer for time multiplexed measurements*/
117+
uint32_t histogram_type; /* RAW, ELEC_CAL, etc */
118+
uint32_t num_tdc; /* Number of histogram channels in this message */
119+
uint32_t num_bins; /* length of histogram(s) for each channel */
120+
uint32_t bins[TMF882X_HIST_NUM_TDC][TMF882X_HIST_NUM_BINS];
121+
};
122+
```
123+
The fields of the message structure are defined as:
124+
125+
| field | Description |
126+
| :---- | :---- |
127+
| capture_num | This is the capture number that this set of histograms is associated with. The capture_num will match the `struct tmf882x_msg_meas_results::result_num` |
128+
| sub_capture | This is the time-multiplexed sub-capture index of this set of histograms. For non-time-multiplexed measurements this value is always zero. |
129+
| histogram_type | This is the histogram type identifier code `enum tmf882x_histogram_type` |
130+
| num_tdc | This is the number of TDC histograms being published |
131+
| num_bins | This is the number of bins in the histograms being published |
132+
| bins | These are the histogram bin values for each TDC. There are two channels per TDC, the first channel histogram occupies bins `[0 : TMF882X_HIST_NUM_BINS/2 - 1]`, the 2nd channel occupies bins `[TMF882X_HIST_NUM_BINS/2 : @ref TMF882X_HIST_NUM_BINS - 1]` |
8133

9134
```c++
10-
void setCursor(uint8_t x, uint8_t y)
135+
void setHistogramHandler(TMF882XHistogramHandler handler)
11136
```
12137
13138
| Parameter | Type | Description |
14139
| :--- | :--- | :--- |
15-
| x | `uint8_t` | The X coordinate of the cursor|
16-
| y | `uint8_t` | The Y coordinate of the cursor|
140+
| handler | `TMF882XHistogramHandler` | The message handler callback C function |
141+
17142
18-
### setColor()
143+
### setStatsHandler()
19144
20-
This method is called to set the current color of the system. This is used by the Arduino `Print` interface functionality
145+
Call this method with a function that is called when measurement statistics data is sent from the AMS sdk.
21146
147+
The passed in function should be of type `TMF882XStatsHandler`, which is defined as:
148+
149+
```C++
150+
typedef void (*TMF882XStatsHandler)(struct tmf882x_msg_meas_stats *message);
151+
```
152+
153+
This function accepts a parameter of type tmf882x_msg_meas_stats, which is defined as:
154+
155+
```C++
156+
struct tmf882x_msg_meas_stats {
157+
struct tmf882x_msg_header hdr;
158+
uint32_t capture_num; /* matches the value of 'result_num' from measure result messages*/
159+
uint32_t sub_capture; /* sub-capture measurement nubmer for time multiplexed measurements*/
160+
uint32_t tdcif_status;
161+
uint32_t iterations_configured;
162+
uint32_t remaining_iterations;
163+
uint32_t accumulated_hits;
164+
uint32_t raw_hits[TMF882X_HIST_NUM_TDC];
165+
uint32_t saturation_cnt[TMF882X_HIST_NUM_TDC];
166+
};
167+
```
168+
The fields of the message structure are defined as:
169+
170+
| field | Description |
171+
| :---- | :---- |
172+
| capture_num | This is the capture number that this set of histograms is associated with. The capture_num will match the `struct tmf882x_msg_meas_results::result_num` |
173+
| sub_capture | This is the time-multiplexed sub-capture index of this set of histograms. For non-time-multiplexed measurements this value is always zero. |
174+
| tdcif_status | This is the tdcif status reported by the device |
175+
| iterations_configured | This is the iterations configured reported by the device |
176+
| remaining_iterations | This is the remaining iterations reported by the device |
177+
| accumulated_hits | This is the accumulated hits reported by the device |
178+
| raw_hits | This is the raw hits reported by the device for each TDC |
179+
| saturation_cnt | This is the saturation count reported by the device for each TDCd |
22180
23181
```c++
24-
void setColor(uint8_t clr)
182+
void setStatsHandler(TMF882XStatsHandler handler)
25183
```
26184

27185
| Parameter | Type | Description |
28186
| :--- | :--- | :--- |
29-
| `clr` | `uint8_t` | The color to set. 0 = black, > 0 = white|
187+
| handler | `TMF882XStatsHandler` | The message handler callback C function |
30188

31-
### getColor()
189+
### setErrorHandler()
32190

33-
This method is called to get the current color of the system. This is used by the Arduino `Print` interface functionality
191+
Call this method with a function that is called when error information is sent from the AMS sdk.
34192

193+
The passed in function should be of type `TMF882XErrorHandler`, which is defined as:
194+
195+
```C++
196+
typedef void (*TMF882XErrorHandler)(struct tmf882x_msg_error *message);
197+
```
198+
199+
This function accepts a parameter of type tmf882x_msg_error, which is defined as:
200+
201+
```C++
202+
struct tmf882x_msg_error {
203+
struct tmf882x_msg_header hdr;
204+
uint32_t err_code;
205+
};
206+
```
207+
The fields of the message structure are defined as:
208+
209+
| field | Description |
210+
| :---- | :---- |
211+
| err_code | This is the error code identifier |
35212

36213
```c++
37-
uint8_t getColor(void)
214+
void setErrorHandler(TMF882XErrorHandler handler)
38215
```
39216
40217
| Parameter | Type | Description |
41218
| :--- | :--- | :--- |
42-
| return value| `uint8_t` | The current color|
219+
| handler | `TMF882XErrorHandler` | The message handler callback C function |
220+
221+
## Measurement Methods

0 commit comments

Comments
 (0)