Statistics
| Branch: | Tag: | Revision:

amiro-lld / templates / periphAL.h @ bb7c5348

History | View | Annotate | Download (12.5 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    1
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 apalSleep(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 Return the interrupt enable status of the GPIO.
104
 *
105
 * @param[in]   gpio      GPIO to check.
106
 * @param[out]  enabled   Flag, indicating whether interrupt is enabled for the GPIO.
107
 *
108
 * @return The status indicates whether the function call was successful.
109
 */
110
static inline apalExitStatus_t apalGpioIsInterruptEnabled(apalGpio_t* gpio, bool* const enabled)
111

    
112
/**
113
 * @brief Get the current on/off state of a control GPIO.
114
 *
115
 * @param[in]   gpio  Control GPIO to read.
116
 * @param[out]  val   Current activation status of the control GPIO.
117
 *
118
 * @return The status indicates whether the function call was successful.
119
 */
120
apalExitStatus_t apalControlGpioGet(const apalControlGpio_t* const cgpio, apalControlGpioState_t* const val);
121

    
122
/**
123
 * @brief Turn a control GPIO 'on' or 'off' respectively.
124
 *
125
 * @param[in] gpio  Control GPIO to set.
126
 * @param[in] val   Activation value to set for the control GPIO.
127
 *
128
 * @return The status indicates whether the function call was successful.
129
 */
130
apalExitStatus_t apalControlGpioSet(const apalControlGpio_t* const cgpio, const apalControlGpioState_t val);
131

    
132
/**
133
 * @brief   Enable or disable the interrupt event functionality.
134
 *
135
 * @param[in] cgpio   Control GPIO to set.
136
 * @param[in] enable  Flag, indicating whether the interrupt shall be activated (true) or deactivated (false).
137
 *
138
 * @return The status indicates whether the function call was successful.
139
 */
140
apalExitStatus_t apalControlGpioSetInterrupt(apalControlGpio_t* const cgpio, const bool enable);
141

    
142
#ifdef __cplusplus
143
}
144
#endif
145

    
146
/*============================================================================*/
147
/* PWM                                                                        */
148
/*============================================================================*/
149

    
150
/**
151
 * @brief PWM driver type.
152
 */
153
typedef osPWMDriver_t apalPWMDriver_t;
154

    
155
#ifdef __cplusplus
156
extern "C" {
157
#endif
158

    
159
/**
160
 * @brief   Set the PWM with given parameters.
161
 *
162
 * @param[in] pwm       PWM driver to set.
163
 * @param[in] channel   Channel of the PWM driver to set.
164
 * @param[in] width     Width to set the channel to.
165
 *
166
 * @return  The status indicates whether the function call was successful.
167
 */
168
apalExitStatus_t apalPWMSet(apalPWMDriver_t* pwm, const apalPWMchannel_t channel, const apalPWMwidth_t width);
169

    
170
/**
171
 * @brief   Retrieve the current frequency of the PWM.
172
 *
173
 * @param[in]  pwm        PWM driver to read.
174
 * @param[out] frequency  The currently set frequency.
175
 *
176
 * @return  The status indicates whether the function call was successful.
177
 */
178
apalExitStatus_t apalPWMGetFrequency(apalPWMDriver_t* pwm, apalPWMfrequency_t* const frequency);
179

    
180
/**
181
 * @brief   Retrieve the current period of the PWM.
182
 *
183
 * @param[in]   pwm     PWM driver to read.
184
 * @param[out]  period  The currently set period.
185
 *
186
 * @return  The status indicates whether the function call was successful.
187
 */
188
apalExitStatus_t apalPWMGetPeriod(apalPWMDriver_t* pwm, apalPWMperiod_t* const period);
189

    
190
#ifdef __cplusplus
191
}
192
#endif
193

    
194
/*============================================================================*/
195
/* QEI                                                                        */
196
/*============================================================================*/
197

    
198
/**
199
 * @brief QEI driver type.
200
 */
201
typedef osQEIDriver_t apaQEIDriver_t;
202

    
203
#ifdef __cplusplus
204
extern "C" {
205
#endif
206

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

    
217
/**
218
 * @brief Gets the current position of the ecnoder.
219
 *
220
 * @param[in]   qei       The QEI driver to use.
221
 * @param[out]  position  The current position of the encoder.
222
 *
223
 * @return The status indicates whether the function call was successful.
224
 */
225
apalExitStatus_t apalQEIGetPosition(apalQEIDriver_t* qei, apalQEICount_t* const position);
226

    
227
/**
228
 * @brief Gets the value range of the encoder.
229
 *
230
 * @param[in]   qei     The QEI driver to use.
231
 * @param[out]  range   The value range of the encoder.
232
 *
233
 * @return The status indicates whether the function call was successful.
234
 */
235
apalExitStatus_t apalQEIGetRange(apalQEIDriver_t* qei, apalQEICount_t* const range);
236

    
237
#ifdef __cplusplus
238
}
239
#endif
240

    
241
/*============================================================================*/
242
/* I2C                                                                        */
243
/*============================================================================*/
244

    
245
/**
246
 * @brief I2C driver type.
247
 */
248
typedef osI2CDriver_t apalI2CDriver_t;
249

    
250
#ifdef __cplusplus
251
extern "C" {
252
#endif
253

    
254
/**
255
 * @brief Transmit data and receive a response.
256
 *
257
 * @param[in]   i2cd      The I2C driver to use.
258
 * @param[in]   addr      Address to write to.
259
 * @param[in]   txbuf     Buffer containing data to send.
260
 * @param[in]   txbytes   Number of bytes to send.
261
 * @param[out]  rxbuf     Buffer to store a response to.
262
 * @param[in]   rxbytes   Number of bytes to receive.
263
 * @param[in]   timeout   Timeout for the function to return (in microseconds).
264
 *
265
 * @return The status indicates whether the function call was succesful or a timeout occurred.
266
 */
267
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);
268

    
269
/**
270
 * @brief Read data from a specific address.
271
 *
272
 * @param[in]   i2cd      The I2C driver to use.
273
 * @param[in]   addr      Address to read.
274
 * @param[out]  rxbuf     Buffer to store the response to.
275
 * @param[in]   rxbytes   Number of bytes to receive.
276
 * @param[in]   timeout   Timeout for the function to return (in microseconds).
277
 *
278
 * @return The status indicates whether the function call was succesful or a timeout occurred.
279
 */
280
apalExitStatus_t apalI2CMasterReceive(apalI2CDriver_t* i2cd, const apalI2Caddr_t addr, uint8_t* const rxbuf, const size_t rxbytes, const apalTime_t timeout);
281

    
282
#ifdef __cplusplus
283
}
284
#endif
285

    
286
/*============================================================================*/
287
/* SPI                                                                        */
288
/*============================================================================*/
289

    
290
/**
291
 * @brief SPI driver type.
292
 */
293
typedef osSPIDriver_t apalSPIDriver_t;
294

    
295
/**
296
 * @brief SPI confguration type.
297
 */
298
typedef osSPIConfig apalSPIConfig_t;
299

    
300
#ifdef __cplusplus
301
extern "C" {
302
#endif
303

    
304
/**
305
 * @brief Reconfigure an SPI driver.
306
 *
307
 * @param[in] spid    The SPI driver to be reconfigured.
308
 * @param[in] config  Configuration to apply.
309
 *
310
 * @return The status indicates whether the function call was succesful.
311
 */
312
static inline apalExitStatus_t apalSPIReconfigure(apalSPIDriver_t* spid, const apalSPIConfig_t* config);
313

    
314
/**
315
 * @brief Transmit and receive data from SPI
316
 *
317
 * @param[in]   spid      The SPI driver to use.
318
 * @param[in]   txData    Buffer containing data to send.
319
 * @param[out]  rxData    Buffer to store.
320
 * @param[in]   length    Number of bytes to send.
321
 *
322
 * @return The status indicates whether the function call was succesful.
323
 */
324
apalExitStatus_t apalSPIExchange(apalSPIDriver_t* spid, const uint8_t* const txData , uint8_t* const rxData, const size_t length);
325

    
326
/**
327
 * @brief Receive data from SPI
328
 *
329
 * @param[in]   spid      The SPI driver to use.
330
 * @param[out]  data      Buffer to store.
331
 * @param[in]   length    Number of bytes to send.
332
 *
333
 * @return The status indicates whether the function call was succesful.
334
 */
335
apalExitStatus_t apalSPIReceive(apalSPIDriver_t* spid, uint8_t* const data, const size_t length);
336

    
337
/**
338
 * @brief Transmit data to SPI
339
 *
340
 * @param[in]   spid      The SPI driver to use.
341
 * @param[in]   data      Buffer containing data to send.
342
 * @param[in]   length    Number of bytes to send.
343
 *
344
 * @return The status indicates whether the function call was succesful.
345
 */
346
apalExitStatus_t apalSPITransmit(apalSPIDriver_t* spid, const uint8_t* const data, const size_t length);
347

    
348
/**
349
 * @brief Transmit data to SPI and receive data afterwards without releasing the bus in between.
350
 *
351
 * @param[in]   spid        The SPI driver to use.
352
 * @param[in]   txData      Transmit data buffer.
353
 * @param[in]   rxData      Receive data buffer.
354
 * @param[in]   txLength    Number of bytes to send.
355
 * @param[in]   rxLength    Number of bytes to receive.
356
 *
357
 * @return The status indicates whether the function call was succesful.
358
 */
359
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);
360

    
361
#ifdef __cplusplus
362
}
363
#endif
364

    
365
/*============================================================================*/
366
/* DEBUG                                                                      */
367
/*============================================================================*/
368

    
369
#ifdef __cplusplus
370
extern "C" {
371
#endif
372

    
373
/**
374
 * @brief Assert function to check a given condition.
375
 * @note  Using a macro is preferable.
376
 *
377
 * @param[in] c   The condition to check.
378
 */
379
void apalDbgAssert(bool c);
380

    
381
/**
382
 * @brief Printf function for messages printed only in debug builds.
383
 *
384
 * @param[in] fmt   Formatted string to print.
385
 */
386
void apalDbgPrintf(fmt, ...);
387

    
388
#ifdef __cplusplus
389
}
390
#endif
391

    
392
#endif /* AMIROOS_PERIPHAL_H */
393