Remi Beges / DistantIO

Framework for reading and writing variables in real time on any MBED platform.

DistantIO

This is the C implementation of the DistantIO slave framework.

Library is working but slight API breaks may occur in the future. C++ version is also in development.

To get the master-side implementation, see https://github.com/Overdrivr/DistantIO

distantio.h@6:72d46dbdbe7a, 2015-10-16 (annotated)

Committer:
Overdrivr
Date:
Fri Oct 16 16:16:19 2015 +0000
Revision:
6:72d46dbdbe7a
Parent:
5:e8936f38a338 
removed 'static' keyword in front arrays that just increase RAM usage (premature optimization)

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Overdrivr 2:f2c816b681e3 1 /*
Overdrivr 2:f2c816b681e3 2 * distantio.h
Overdrivr 2:f2c816b681e3 3 *
Overdrivr 2:f2c816b681e3 4 * Created on: Oct 13, 2014
Overdrivr 2:f2c816b681e3 5 * Author: B48923
Overdrivr 2:f2c816b681e3 6 */
Overdrivr 1:aaffeb93f99b 7
Overdrivr 0:c4676d32d381 8 #ifndef DISTANTIO_H_
Overdrivr 0:c4676d32d381 9 #define DISTANTIO_H_
Overdrivr 0:c4676d32d381 10
Overdrivr 0:c4676d32d381 11 #include <stdint.h>
Overdrivr 0:c4676d32d381 12
Overdrivr 3:135f55b5334e 13 #define FRAMESIZE 20
Overdrivr 3:135f55b5334e 14 #define DATASIZE 8
Overdrivr 3:135f55b5334e 15 #define DATASTART 10
Overdrivr 0:c4676d32d381 16 #define VARIABLES_AMOUNT 256
Overdrivr 0:c4676d32d381 17 #define GROUPS_AMOUNT 128
Overdrivr 3:135f55b5334e 18 #define NAMESIZE 14
Overdrivr 0:c4676d32d381 19
Overdrivr 4:d675ad9c57ff 20 /** Data types that can be exchanged effortlessly with the computer.
Overdrivr 4:d675ad9c57ff 21 *
Overdrivr 4:d675ad9c57ff 22 *
Overdrivr 4:d675ad9c57ff 23 */
Overdrivr 0:c4676d32d381 24 typedef enum dio_type dio_type;
Overdrivr 0:c4676d32d381 25 enum dio_type
Overdrivr 0:c4676d32d381 26 {
Overdrivr 0:c4676d32d381 27 dio_type_FLOAT = 0x00,
Overdrivr 0:c4676d32d381 28 dio_type_UINT8 = 0x01,
Overdrivr 0:c4676d32d381 29 dio_type_UINT16 = 0x02,
Overdrivr 0:c4676d32d381 30 dio_type_UINT32 = 0x03,
Overdrivr 0:c4676d32d381 31 dio_type_INT8 = 0x04,
Overdrivr 0:c4676d32d381 32 dio_type_INT16 = 0x05,
Overdrivr 0:c4676d32d381 33 dio_type_INT32 = 0x06,
Overdrivr 0:c4676d32d381 34 };
Overdrivr 0:c4676d32d381 35
Overdrivr 0:c4676d32d381 36 typedef struct variable variable;
Overdrivr 0:c4676d32d381 37 struct variable
Overdrivr 0:c4676d32d381 38 {
Overdrivr 0:c4676d32d381 39 uint8_t* ptr;
Overdrivr 0:c4676d32d381 40 uint16_t size;
Overdrivr 0:c4676d32d381 41 uint8_t writeable;
Overdrivr 0:c4676d32d381 42 uint16_t id;
Overdrivr 0:c4676d32d381 43 dio_type type;
Overdrivr 3:135f55b5334e 44 char name[NAMESIZE];
Overdrivr 0:c4676d32d381 45 uint8_t send;
Overdrivr 0:c4676d32d381 46 uint8_t groupID;
Overdrivr 2:f2c816b681e3 47 float refresh_rate;
Overdrivr 2:f2c816b681e3 48 float last_refreshed;
Overdrivr 0:c4676d32d381 49 };
Overdrivr 0:c4676d32d381 50
Overdrivr 0:c4676d32d381 51 typedef struct group group;
Overdrivr 0:c4676d32d381 52 struct group
Overdrivr 0:c4676d32d381 53 {
Overdrivr 3:135f55b5334e 54 char name[NAMESIZE];
Overdrivr 0:c4676d32d381 55 uint8_t groupID;
Overdrivr 0:c4676d32d381 56 };
Overdrivr 0:c4676d32d381 57
Overdrivr 0:c4676d32d381 58 //typedef struct log log;
Overdrivr 0:c4676d32d381 59 struct log
Overdrivr 0:c4676d32d381 60 {
Overdrivr 0:c4676d32d381 61 variable variables[VARIABLES_AMOUNT];
Overdrivr 0:c4676d32d381 62 group groups[GROUPS_AMOUNT];
Overdrivr 0:c4676d32d381 63 uint16_t amount;
Overdrivr 0:c4676d32d381 64 uint8_t current_group_id;
Overdrivr 0:c4676d32d381 65 };
Overdrivr 0:c4676d32d381 66
Overdrivr 4:d675ad9c57ff 67 /** Initializes the DistantIO framework
Overdrivr 4:d675ad9c57ff 68 * This is used to create the internal log
Overdrivr 4:d675ad9c57ff 69 * @note Don't forget to initialize the frame delimiting protocol @see protocol.h
Overdrivr 4:d675ad9c57ff 70 *
Overdrivr 4:d675ad9c57ff 71 */
Overdrivr 4:d675ad9c57ff 72 void dIO_init();
Overdrivr 0:c4676d32d381 73
Overdrivr 4:d675ad9c57ff 74 /** Registers a variable in the log. This function is usually called during program initalization
Overdrivr 4:d675ad9c57ff 75 * All this data is stored in a descriptor that can be queried from master-side.
Overdrivr 4:d675ad9c57ff 76 * @param ptr Pointer to the memory adress of the variable. Not extremely safe but that's all can be done with C
Overdrivr 4:d675ad9c57ff 77 * @param size Size of the variable. Use sizeof(..) to always provide the right size. This will be improved when switching over C++ templated class
Overdrivr 4:d675ad9c57ff 78 * @param type type of the variable. For a list of possible types @see dio_type
Overdrivr 4:d675ad9c57ff 79 * @param writeable 0 if the variable is not writeable from master-side, 1 otherwise.
Overdrivr 4:d675ad9c57ff 80 * @param name Name of the variable to identify the variable easily master-side. Names don't have to be uniques, and are limited to 14 characters.
Overdrivr 4:d675ad9c57ff 81 * @param refresh_rate Time interval in seconds between two consecutive sends of the variable to the master. 0 means the variable is send on each call to @see dIO_update
Overdrivr 4:d675ad9c57ff 82 * @returns
Overdrivr 4:d675ad9c57ff 83 0 if everything ok
Overdrivr 4:d675ad9c57ff 84 1 if the internal log is full.
Overdrivr 4:d675ad9c57ff 85 */
Overdrivr 4:d675ad9c57ff 86 uint8_t dIO_var(void* ptr, uint16_t size, dio_type type, uint8_t writeable, char* name, float refresh_rate = 0);
Overdrivr 0:c4676d32d381 87
Overdrivr 4:d675ad9c57ff 88 /** Starts a new group. Any subsequent call to @dio_var will register the variable under this new group.
Overdrivr 4:d675ad9c57ff 89 * Groups also have descriptors that can be queried from master-side.
Overdrivr 5:e8936f38a338 90 * @param groupname name of the variable group. Limited to 14 characters.
Overdrivr 4:d675ad9c57ff 91 *
Overdrivr 4:d675ad9c57ff 92 */
Overdrivr 4:d675ad9c57ff 93 void dIO_group(char* groupname);
Overdrivr 4:d675ad9c57ff 94
Overdrivr 4:d675ad9c57ff 95 /** Decodes the contents of a new received frame. Frame of unvalid sizes or with unvalid CRCs are immediatly discarded.
Overdrivr 4:d675ad9c57ff 96 * @param data pointer to the data buffer start adress
Overdrivr 4:d675ad9c57ff 97 * @param datasize size in bytes of the data buffer
Overdrivr 4:d675ad9c57ff 98 */
Overdrivr 4:d675ad9c57ff 99 void dIO_decode(uint8_t* data,uint16_t datasize);
Overdrivr 0:c4676d32d381 100
Overdrivr 4:d675ad9c57ff 101 /** Updates the internal state of DistantIO. Variables will be sent upon calling this method.
Overdrivr 4:d675ad9c57ff 102 * It is recommended to call this method approximately 10 times per second to keep impact on mbed device low while having good refresh rate master side.
Overdrivr 4:d675ad9c57ff 103 * @note execution time of this function is directly related to the amount of registered variables, especially with small or 0 refresh rates.
Overdrivr 4:d675ad9c57ff 104 * @param elapsed time since the beginning of the program
Overdrivr 4:d675ad9c57ff 105 *
Overdrivr 4:d675ad9c57ff 106 */
Overdrivr 4:d675ad9c57ff 107 void dIO_update(float current_time);
Overdrivr 4:d675ad9c57ff 108
Overdrivr 4:d675ad9c57ff 109 /** Sends an alive signal to the master to signal the mbed device is running and communication is working.
Overdrivr 4:d675ad9c57ff 110 * You should call this method approximately every half second.
Overdrivr 4:d675ad9c57ff 111 *
Overdrivr 4:d675ad9c57ff 112 */
Overdrivr 4:d675ad9c57ff 113 void dIO_send_alive();
Overdrivr 0:c4676d32d381 114
Overdrivr 5:e8936f38a338 115 /** Manual mode for sending special data in case of particular events.
Overdrivr 5:e8936f38a338 116 * This is useful to debug issues happening much faster than human perception, because this data will be exported master-side to an excel file.
Overdrivr 5:e8936f38a338 117 * This mode can also support arrays by calling it for each array index and specifying that index as last parameter.
Overdrivr 5:e8936f38a338 118 * Master-side, data is sorted in a hierchical manner, first by name, then by recording time, then by index (see parameters).
Overdrivr 5:e8936f38a338 119 * @param ptr Pointer to the data start adress
Overdrivr 5:e8936f38a338 120 * @param size Size in bytes of the data. Use sizeof(..) to avoid mistakes.
Overdrivr 5:e8936f38a338 121 * @param type Type of the variable. For a list of possible types @see dio_type
Overdrivr 5:e8936f38a338 122 * @param name Quick custom name for the variable. Limited to 2 characters for now.
Overdrivr 5:e8936f38a338 123 * @param recordingtime User-specified field intented for associating a specific time with the data
Overdrivr 5:e8936f38a338 124 * @param index User-specified field for associating a specific index to the data.
Overdrivr 5:e8936f38a338 125 */
Overdrivr 5:e8936f38a338 126 void dIO_emergency_send(void* ptr, uint16_t size, dio_type type, char* name, float recordingtime, uint16_t index = 0);
Overdrivr 5:e8936f38a338 127
Overdrivr 0:c4676d32d381 128 #endif /* DISTANTIO_H_ */