epicardium.h 3.83 KB
Newer Older
Rahix's avatar
Rahix committed
1
2
3
#ifndef _EPICARDIUM_H
#define _EPICARDIUM_H
#include <stdint.h>
4
5
#include <stddef.h>
#include <errno.h>
Rahix's avatar
Rahix committed
6
7

#ifndef API
Rahix's avatar
Rahix committed
8
#define API(id, def) def
Rahix's avatar
Rahix committed
9
10
#endif

Rahix's avatar
Rahix committed
11
12
13
14
/* clang-format off */
#define API_UART_WRITE         0x1
#define API_UART_READ          0x2
#define API_LEDS_SET           0x3
Rahix's avatar
Rahix committed
15
#define API_VIBRA_SET          0x4
16
#define API_VIBRA_VIBRATE      0x5
17
#define API_STREAM_READ        0x6
Rahix's avatar
Rahix committed
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
/* clang-format on */

/**
 * UART/Serial Interface
 * =====================
 */

/**
 * Write a string to all connected serial devices.  This includes:
 *
 * - Real UART, whose pins are mapped onto USB-C pins.  Accessible via the HW-debugger.
 * - A CDC-ACM device available via USB.
 * - Maybe, in the future, bluetooth serial?
 *
 * :param str:  String to write.  Does not necessarily have to be NULL-terminated.
 * :param length:  Amount of bytes to print.
 */
Rahix's avatar
Rahix committed
35
API(API_UART_WRITE, void epic_uart_write_str(const char *str, intptr_t length));
Rahix's avatar
Rahix committed
36

Rahix's avatar
Rahix committed
37
38
39
40
41
42
43
/**
 * Blocking read a single character from any connected serial device.
 * ``epic_uart_read_chr`` only returns
 * once one byte has been read.
 *
 * :return:  The byte.
 */
Rahix's avatar
Rahix committed
44
45
API(API_UART_READ, char epic_uart_read_chr(void));

Rahix's avatar
Rahix committed
46
47
48
49
50
51
52
53
54
55
56
57
58
/**
 * LEDs
 * ====
 */

/**
 * Set one of card10's RGB LEDs to a certain color.
 *
 * :param led:  Which led to set.  0-10 are the leds on the top and 11-14 are the 4 "ambient" leds.
 * :param r:  Red component of the color.
 * :param g:  Green component of the color.
 * :param b:  Blue component of the color.
 */
59
60
API(API_LEDS_SET, void epic_leds_set(int led, uint8_t r, uint8_t g, uint8_t b));

61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
/**
 * Sensor Data Streams
 * ===================
 * A few of card10's sensors can do continuous measurements.  To allow
 * performant access to their data, the following function is made for generic
 * access to streams.
 */

/**
 * Read sensor data into a buffer.  ``epic_stream_read()`` will read as many
 * sensor data packets as possible into ``buf`` and return as soon as possible.
 * It will poke the sensor driver once to check whether new data can be fetched.
 * If there is no new sensor data, ``epic_stream_read()`` will return ``0`` and
 * not touch ``buf``.  Otherwise it will return the number of data packets which
 * were read into ``buf``.
 *
 * :param int sd: Sensor Descriptor.  You get sensor descriptors as return
 *    values when activating the respective sensors.
 * :param void* buf: Buffer where sensor data should be read into.
 * :param size_t count: How many bytes to read at max.  Note that fewer bytes
 *    might be read.  In most cases, this should be ``sizeof(buf)``.
 * :return: Number of data packets read (**not** number of bytes) or a negative
 *    error value.  Possible errors:
 *
 *    - ``-ENODEV``: Sensor is not currently available.
 *    - ``-EBADF``: The given sensor descriptor is unknown.
 *    - ``-EINVAL``:  If ``count`` is not a multiple of the sensor data packet
 *      size.
 *
 * **Example**:
 *
 * .. code-block:: cpp
 *
 *    #include "epicardium.h"
 *
 *    struct foo_measurement sensor_data[16];
 *    int foo_sd, n;
 *
 *    foo_sd = epic_foo_sensor_enable(9001);
 *
 *    while (1) {
 *            n = epic_stream_read(
 *                    foo_sd,
 *                    &sensor_data,
 *                    sizeof(sensor_data)
 *            );
 *
 *            // Print out the measured sensor samples
 *            for (int i = 0; i < n; i++) {
 *                    printf("Measured: %?\n", sensor_data[i]);
 *            }
 *    }
 */
API(API_STREAM_READ, int epic_stream_read(int sd, void *buf, size_t count));

Rahix's avatar
Rahix committed
116
117
118
119
120
121
122
123
124
125
/**
 * Misc
 * ====
 */

/**
 * Turn vibration motor on or off
 *
 * :param status: 1 to turn on, 0 to turn off.
 */
Gerd's avatar
Gerd committed
126
127
API(API_VIBRA_SET, void epic_vibra_set(int status));

128
129
130
131
132
133
134
/**
 * Turn vibration motor on for a given time
 *
 * :param millis: number of milliseconds to run the vibration motor.
 */
API(API_VIBRA_VIBRATE, void epic_vibra_vibrate(int millis));

Rahix's avatar
Rahix committed
135
#endif /* _EPICARDIUM_H */