Skip to content

Commit 878cbd7

Browse files
gonzolivelygonzolively
authored
Adding RNG sensor API documentating (#31)
* Moved execution environment to top for most APIs, and removed function from the GPIO documentation. * Removed mention of wasm_exec_env_t from the messaging docs * Added the RNG sensor and restructured the docs slightly.
1 parent d590eab commit 878cbd7

3 files changed

Lines changed: 169 additions & 4 deletions

File tree

docs/reference/apis/container-api/sensors.md renamed to docs/reference/apis/container-api/sensors/general_sensors.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
---
2-
title: Sensors
2+
title: General Sensors
33
layout: default
4-
parent: Container
4+
parent: Sensors
55
---
66

7-
# Sensors
7+
# General Sensors
88
{: .no_toc }
99

1010
The Sensors API provides a unified interface for discovering, configuring, and retrieving data from various hardware sensors in Ocre containers. It supports multiple sensor types and channels, allowing applications to interact with environmental, motion, and position sensing capabilities.
@@ -467,4 +467,4 @@ int main() {
467467
| [`sensor_get_channel`](#get-sensor-channel) | Gets channel data | `sample`: Sensor sample<br/>`channel`: Channel to retrieve | `ocre_sensor_value_t` structure | N/A |
468468
| [`ocre_sensors_set_trigger`](#set-sensor-trigger) | Sets sensor trigger | `sensor_handle`: Target sensor<br/>`channel`: Target channel<br/>`trigger_type`: Trigger type<br/>`callback`: Callback function<br/>`subscription_id`: `ID` output | Status code | `SENSOR_API_STATUS_OK`,<br/>`SENSOR_API_STATUS_ERROR` |
469469
| [`ocre_sensors_clear_trigger`](#clear-sensor-trigger) | Removes sensor trigger | `sensor_handle`: Target sensor<br/>`channel`: Target channel<br/>`subscription_id`: Subscription to remove | Status code | `SENSOR_API_STATUS_OK`,<br/>`SENSOR_API_STATUS_ERROR` |
470-
| [`ocre_sensors_cleanup`](#clean-up-sensor-environment) | Cleans up resources | None | Status code | `SENSOR_API_STATUS_OK`,<br/>`SENSOR_API_STATUS_ERROR` |
470+
| [`ocre_sensors_cleanup`](#clean-up-sensor-environment) | Cleans up resources | None | Status code | `SENSOR_API_STATUS_OK`,<br/>`SENSOR_API_STATUS_ERROR` |

‎docs/reference/apis/container-api/sensors/index.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: Sensors
3+
layout: default
4+
parent: Container
5+
has_toc: false
6+
---
7+
8+
# Sensors APIs
9+
10+
Sensors APIs provide unified interfaces for containers to discover, configure, and retrieve data from various hardware sensors. These APIs enable applications to interact with environmental, motion, position, and other specialized sensing capabilities in a consistent manner.
11+
12+
---
13+
14+
## Available APIs
15+
16+
Below are the sensor APIs available for Ocre containers, providing access to different types of sensor functionality.
17+
18+
| API | Description |
19+
|-----|-------------|
20+
| [General Sensors](general_sensors) | Unified interface for working with all sensor types, including discovery, configuration, and data retrieval |
21+
| [RNG Sensor](rng_sensor) | Hardware-backed random number generation capabilities with seamless integration into the sensor framework |

‎docs/reference/apis/container-api/sensors/rng_sensor.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
title: RNG Sensor
3+
layout: default
4+
parent: Sensors
5+
---
6+
7+
# RNG Sensor
8+
{: .no_toc }
9+
10+
The RNG sensor is pre-integrated with the Ocre sensor subsystem and built into the standard Ocre runtime. Users can access it through the [general Sensors](general_sensors.md) API without needing any additional header files, initialization steps, or configuration.
11+
12+
---
13+
14+
## Table of Contents
15+
{: .no_toc }
16+
17+
Navigate this comprehensive API reference using the links below.
18+
19+
<details close markdown="block">
20+
<summary>
21+
Click to expand
22+
</summary>
23+
{: .text-delta }
24+
1. TOC
25+
{:toc}
26+
</details>
27+
28+
---
29+
30+
## Header File
31+
32+
```c
33+
#include "rng_sensor.h"
34+
```
35+
36+
{: .highlight Note}
37+
The RNG sensor header file is for internal use only in the Ocre runtime implementation. Application developers should NOT include this header file in their code. Instead, they should only include the general sensors API header (`ocre_sensors.h`) and access the RNG sensor through the [general Sensors](general_sensors.md) API.
38+
39+
---
40+
41+
## Methods
42+
43+
For end users, there are no additional methods specific to the RNG sensor beyond those provided by the general Sensors API. The RNG sensor is accessed entirely through the standard sensor interface.
44+
45+
The internal RNG sensor implementation includes:
46+
47+
### RNG Sensor Initialization
48+
49+
```c
50+
int rng_sensor_init(const struct device *dev);
51+
```
52+
53+
This function is for internal use only and is automatically called during system initialization. Users do not need to call this function.
54+
55+
---
56+
57+
## Usage with Sensors API
58+
59+
The RNG sensor provides a random number generation channel that can be accessed through the standard Sensors API.
60+
61+
**To use the RNG sensor:**
62+
63+
1. Include only the general sensors header: `#include "ocre_sensors.h"`
64+
2. Initialize the sensor subsystem with `ocre_sensors_init()`
65+
3. Discover available sensors with `ocre_sensors_discover()`
66+
4. Find the RNG sensor by looking for a sensor that supports the channel `SENSOR_CHAN_CUSTOM + 1` (value 2)
67+
5. Get a handle and open the sensor using standard API calls
68+
6. Read random values using `ocre_sensors_read()` with channel value `SENSOR_CHAN_CUSTOM + 1`
69+
70+
---
71+
72+
## Examples
73+
74+
### Basic RNG Sensor Usage
75+
76+
```c
77+
#include <stdio.h>
78+
#include "ocre_sensors.h"
79+
80+
int main() {
81+
// Initialize the sensors subsystem
82+
if (ocre_sensors_init(0) != 0) {
83+
printf("Failed to initialize sensors\n");
84+
return -1;
85+
}
86+
87+
// Discover available sensors
88+
int sensor_count = ocre_sensors_discover();
89+
if (sensor_count <= 0) {
90+
printf("Failed to discover sensors\n");
91+
return -1;
92+
}
93+
94+
printf("Discovered %d sensors\n", sensor_count);
95+
96+
// Find RNG sensor
97+
int rng_sensor_id = -1;
98+
for (int i = 0; i < sensor_count; i++) {
99+
int channel_count = ocre_sensors_get_channel_count(i);
100+
101+
// Check each channel of this sensor
102+
for (int j = 0; j < channel_count; j++) {
103+
int channel_type = ocre_sensors_get_channel_type(i, j);
104+
105+
// Check if this is an RNG channel (using SENSOR_CHAN_CUSTOM + 1 value)
106+
if (channel_type == 2) { // SENSOR_CHAN_CUSTOM + 1 = 2
107+
rng_sensor_id = i;
108+
break;
109+
}
110+
}
111+
112+
if (rng_sensor_id >= 0) break;
113+
}
114+
115+
if (rng_sensor_id < 0) {
116+
printf("RNG sensor not found\n");
117+
return -1;
118+
}
119+
120+
// Get handle for the RNG sensor
121+
ocre_sensor_handle_t rng_handle = ocre_sensors_get_handle(rng_sensor_id);
122+
if (rng_handle < 0) {
123+
printf("Failed to get handle for RNG sensor\n");
124+
return -1;
125+
}
126+
127+
// Open the RNG sensor
128+
if (ocre_sensors_open(rng_handle) != 0) {
129+
printf("Failed to open RNG sensor\n");
130+
return -1;
131+
}
132+
133+
// Read a random value, using SENSOR_CHAN_CUSTOM + 1 (value 2) as the channel
134+
int random_value = ocre_sensors_read(rng_sensor_id, 2); // Channel 2 is the RNG channel
135+
if (random_value < 0) {
136+
printf("Failed to read random value\n");
137+
return -1;
138+
}
139+
140+
printf("Random value: %d\n", random_value);
141+
142+
return 0;
143+
}
144+
```

0 commit comments

Comments
 (0)