Statistics
| Branch: | Tag: | Revision:

amiro-lld / templates / periphAL.h @ 86e60b45

History | View | Annotate | Download (11.4 KB)

1
/*
2
AMiRo-LLD is a compilation of low-level hardware drivers for the Autonomous Mini Robot (AMiRo) platform.
3
Copyright (C) 2016..2019  Thomas Schöpping et al.
4

5
This program is free software: you can redistribute it and/or modify
6
it under the terms of the GNU Lesser General Public License as published by
7
the Free Software Foundation, either version 3 of the License, or
8
(at your option) any later version.
9

10
This program is distributed in the hope that it will be useful,
11
but WITHOUT ANY WARRANTY; without even the implied warranty of
12
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13
GNU Lesser General Public License for more details.
14

15
You should have received a copy of the GNU Lesser General Public License
16
along with this program.  If not, see <http://www.gnu.org/licenses/>.
17
*/
18

    
19
#ifndef AMIROLLD_PERIPHAL_H
20
#define AMIROLLD_PERIPHAL_H
21

    
22
#include <amiro-lld.h>
23

    
24
/*============================================================================*/
25
/* VERSION                                                                    */
26
/*============================================================================*/
27

    
28
/**
29
 * @brief   The periphery abstraction layer interface major version.
30
 * @note    Changes of the major version imply incompatibilities.
31
 */
32
#define PERIPHAL_VERSION_MAJOR    1
33

    
34
/**
35
 * @brief   The periphery abstraction layer interface minor version.
36
 * @note    A higher minor version implies new functionalty, but all old interfaces are still available.
37
 */
38
#define PERIPHAL_VERSION_MINOR    0
39

    
40
/*============================================================================*/
41
/* DEPENDENCIES                                                               */
42
/*============================================================================*/
43

    
44
/*============================================================================*/
45
/* GENERAL                                                                    */
46
/*============================================================================*/
47

    
48
#ifdef __cplusplus
49
extern "C" {
50
#endif
51

    
52
/**
53
 * @brief Delay execution by a specific number of microseconds.
54
 *
55
 * @param[in]   us    Time to sleep until execution continues in microseconds.
56
 */
57
void usleep(apalTime_t us);
58

    
59
#ifdef __cplusplus
60
}
61
#endif
62

    
63
/*============================================================================*/
64
/* GPIO                                                                       */
65
/*============================================================================*/
66

    
67
typedef osGpio_t apalGpio_t;
68

    
69
#ifdef __cplusplus
70
extern "C" {
71
#endif
72

    
73
/**
74
 * @brief Read the current value of a GPIO pin.
75
 *
76
 * @param[in]   gpio  GPIO to read.
77
 * @param[out]  val   Current value of the GPIO.
78
 *
79
 * @return The status indicates whether the function call was successful.
80
 */
81
apalExitStatus_t apalGpioRead(apalGpio_t* gpio, apalGpioState_t* const val);
82

    
83
/**
84
 * @brief Set the value of a GPIO pin.
85
 *
86
 * @param[in] gpio  GPIO to write.
87
 * @param[in] val   Value to set for the GPIO.
88
 *
89
 * @return The status indicates whether the function call was successful.
90
 */
91
apalExitStatus_t apalGpioWrite(apalGpio_t* gpio, const apalGpioState_t val);
92

    
93
/**
94
 * @brief Toggle the output of a GPIO.
95
 *
96
 * @param[in] gpio  GPIO to toggle.
97
 *
98
 * @return The status indicates whether the function call was successful.
99
 */
100
apalExitStatus_t apalGpioToggle(apalGpio_t* gpio);
101

    
102
/**
103
 * @brief Get the current on/off state of a control GPIO.
104
 *
105
 * @param[in]   gpio  Control GPIO to read.
106
 * @param[out]  val   Current activation status of the control GPIO.
107
 *
108
 * @return The status indicates whether the function call was successful.
109
 */
110
apalExitStatus_t apalControlGpioGet(const apalControlGpio_t* const cgpio, apalControlGpioState_t* const val);
111

    
112
/**
113
 * @brief Turn a control GPIO 'on' or 'off' respectively.
114
 *
115
 * @param[in] gpio  Control GPIO to set.
116
 * @param[in] val   Activation value to set for the control GPIO.
117
 *
118
 * @return The status indicates whether the function call was successful.
119
 */
120
apalExitStatus_t apalControlGpioSet(const apalControlGpio_t* const cgpio, const apalControlGpioState_t val);
121

    
122
#ifdef __cplusplus
123
}
124
#endif
125

    
126
/*============================================================================*/
127
/* PWM                                                                        */
128
/*============================================================================*/
129

    
130
/**
131
 * @brief PWM driver type.
132
 */
133
typedef osPWMDriver_t apalPWMDriver_t;
134

    
135
#ifdef __cplusplus
136
extern "C" {
137
#endif
138

    
139
/**
140
 * @brief   Set the PWM with given parameters.
141
 *
142
 * @param[in] pwm       PWM driver to set.
143
 * @param[in] channel   Channel of the PWM driver to set.
144
 * @param[in] width     Width to set the channel to.
145
 *
146
 * @return  The status indicates whether the function call was successful.
147
 */
148
apalExitStatus_t apalPWMSet(apalPWMDriver_t* pwm, const apalPWMchannel_t channel, const apalPWMwidth_t width);
149

    
150
/**
151
 * @brief   Retrieve the current frequency of the PWM.
152
 *
153
 * @param[in]  pwm        PWM driver to read.
154
 * @param[out] frequency  The currently set frequency.
155
 *
156
 * @return  The status indicates whether the function call was successful.
157
 */
158
apalExitStatus_t apalPWMGetFrequency(apalPWMDriver_t* pwm, apalPWMfrequency_t* const frequency);
159

    
160
/**
161
 * @brief   Retrieve the current period of the PWM.
162
 *
163
 * @param[in]   pwm     PWM driver to read.
164
 * @param[out]  period  The currently set period.
165
 *
166
 * @return  The status indicates whether the function call was successful.
167
 */
168
apalExitStatus_t apalPWMGetPeriod(apalPWMDriver_t* pwm, apalPWMperiod_t* const period);
169

    
170
#ifdef __cplusplus
171
}
172
#endif
173

    
174
/*============================================================================*/
175
/* QEI                                                                        */
176
/*============================================================================*/
177

    
178
/**
179
 * @brief QEI driver type.
180
 */
181
typedef osQEIDriver_t apaQEIDriver_t;
182

    
183
#ifdef __cplusplus
184
extern "C" {
185
#endif
186

    
187
/**
188
 * @brief Gets the direction of the last transition.
189
 *
190
 * @param[in]   qei         The QEI driver to use.
191
 * @param[out]  direction   The direction of the last transition.
192
 *
193
 * @return The status indicates whether the function call was successful.
194
 */
195
apalExitStatus_t apalQEIGetDirection(apalQEIDriver_t* qei, apalQEIDirection_t* const direction);
196

    
197
/**
198
 * @brief Gets the current position of the ecnoder.
199
 *
200
 * @param[in]   qei       The QEI driver to use.
201
 * @param[out]  position  The current position of the encoder.
202
 *
203
 * @return The status indicates whether the function call was successful.
204
 */
205
apalExitStatus_t apalQEIGetPosition(apalQEIDriver_t* qei, apalQEICount_t* const position);
206

    
207
/**
208
 * @brief Gets the value range of the encoder.
209
 *
210
 * @param[in]   qei     The QEI driver to use.
211
 * @param[out]  range   The value range of the encoder.
212
 *
213
 * @return The status indicates whether the function call was successful.
214
 */
215
apalExitStatus_t apalQEIGetRange(apalQEIDriver_t* qei, apalQEICount_t* const range);
216

    
217
#ifdef __cplusplus
218
}
219
#endif
220

    
221
/*============================================================================*/
222
/* I2C                                                                        */
223
/*============================================================================*/
224

    
225
/**
226
 * @brief I2C driver type.
227
 */
228
typedef osI2CDriver_t apalI2CDriver_t;
229

    
230
#ifdef __cplusplus
231
extern "C" {
232
#endif
233

    
234
/**
235
 * @brief Transmit data and receive a response.
236
 *
237
 * @param[in]   i2cd      The I2C driver to use.
238
 * @param[in]   addr      Address to write to.
239
 * @param[in]   txbuf     Buffer containing data to send.
240
 * @param[in]   txbytes   Number of bytes to send.
241
 * @param[out]  rxbuf     Buffer to store a response to.
242
 * @param[in]   rxbytes   Number of bytes to receive.
243
 * @param[in]   timeout   Timeout for the function to return (in microseconds).
244
 *
245
 * @return The status indicates whether the function call was succesful or a timeout occurred.
246
 */
247
apalExitStatus_t apalI2CMasterTransmit(apalI2CDriver_t* i2cd, const apalI2Caddr_t addr, const uint8_t* const txbuf, const size_t txbytes, uint8_t* const rxbuf, const size_t rxbytes, const apalTime_t timeout);
248

    
249
/**
250
 * @brief Read data from a specific address.
251
 *
252
 * @param[in]   i2cd      The I2C driver to use.
253
 * @param[in]   addr      Address to read.
254
 * @param[out]  rxbuf     Buffer to store the response to.
255
 * @param[in]   rxbytes   Number of bytes to receive.
256
 * @param[in]   timeout   Timeout for the function to return (in microseconds).
257
 *
258
 * @return The status indicates whether the function call was succesful or a timeout occurred.
259
 */
260
apalExitStatus_t apalI2CMasterReceive(apalI2CDriver_t* i2cd, const apalI2Caddr_t addr, uint8_t* const rxbuf, const size_t rxbytes, const apalTime_t timeout);
261

    
262
#ifdef __cplusplus
263
}
264
#endif
265

    
266
/*============================================================================*/
267
/* SPI                                                                        */
268
/*============================================================================*/
269

    
270
/**
271
 * @brief SPI driver type.
272
 */
273
typedef osSPIDriver_t apalSPIDriver_t;
274

    
275
#ifdef __cplusplus
276
extern "C" {
277
#endif
278

    
279
/**
280
 * @brief Transmit and receive data from SPI
281
 *
282
 * @param[in]   spid      The SPI driver to use.
283
 * @param[in]   txData    Buffer containing data to send.
284
 * @param[out]  rxData    Buffer to store.
285
 * @param[in]   length    Number of bytes to send.
286
 *
287
 * @return The status indicates whether the function call was succesful.
288
 */
289
apalExitStatus_t apalSPIExchange(apalSPIDriver_t* spid, const uint8_t* const txData , uint8_t* const rxData, const size_t length);
290

    
291
/**
292
 * @brief Receive data from SPI
293
 *
294
 * @param[in]   spid      The SPI driver to use.
295
 * @param[out]  data      Buffer to store.
296
 * @param[in]   length    Number of bytes to send.
297
 *
298
 * @return The status indicates whether the function call was succesful.
299
 */
300
apalExitStatus_t apalSPIReceive(apalSPIDriver_t* spid, uint8_t* const data, const size_t length);
301

    
302
/**
303
 * @brief Transmit data to SPI
304
 *
305
 * @param[in]   spid      The SPI driver to use.
306
 * @param[in]   data      Buffer containing data to send.
307
 * @param[in]   length    Number of bytes to send.
308
 *
309
 * @return The status indicates whether the function call was succesful.
310
 */
311
apalExitStatus_t apalSPITransmit(apalSPIDriver_t* spid, const uint8_t* const data, const size_t length);
312

    
313
/**
314
 * @brief Transmit data to SPI and receive data afterwards without releasing the bus in between.
315
 *
316
 * @param[in]   spid        The SPI driver to use.
317
 * @param[in]   txData      Transmit data buffer.
318
 * @param[in]   rxData      Receive data buffer.
319
 * @param[in]   txLength    Number of bytes to send.
320
 * @param[in]   rxLength    Number of bytes to receive.
321
 *
322
 * @return The status indicates whether the function call was succesful.
323
 */
324
static inline apalExitStatus_t apalSPITransmitAndReceive(apalSPIDriver_t* spid, const uint8_t* const txData , uint8_t* const rxData, const size_t txLength, const size_t rxLength);
325

    
326
#ifdef __cplusplus
327
}
328
#endif
329

    
330
/*============================================================================*/
331
/* DEBUG                                                                      */
332
/*============================================================================*/
333

    
334
#ifdef __cplusplus
335
extern "C" {
336
#endif
337

    
338
/**
339
 * @brief Assert function to check a given condition.
340
 * @note  Using a macro is preferable.
341
 *
342
 * @param[in] c   The condition to check.
343
 */
344
void apalDbgAssert(bool c);
345

    
346
/**
347
 * @brief Printf function for messages printed only in debug builds.
348
 *
349
 * @param[in] fmt   Formatted string to print.
350
 */
351
void apalDbgPrintf(fmt, ...);
352

    
353
#ifdef __cplusplus
354
}
355
#endif
356

    
357
#endif /* AMIROOS_PERIPHAL_H */
358