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
Diff: distantio.h
- Revision:
- 4:d675ad9c57ff
- Parent:
- 3:135f55b5334e
- Child:
- 5:e8936f38a338
diff -r 135f55b5334e -r d675ad9c57ff distantio.h --- a/distantio.h Mon Oct 12 13:29:40 2015 +0000 +++ b/distantio.h Tue Oct 13 12:20:44 2015 +0000 @@ -17,6 +17,10 @@ #define GROUPS_AMOUNT 128 #define NAMESIZE 14 +/** Data types that can be exchanged effortlessly with the computer. + * + * + */ typedef enum dio_type dio_type; enum dio_type { @@ -60,16 +64,52 @@ uint8_t current_group_id; }; -void init_distantio(); +/** Initializes the DistantIO framework + * This is used to create the internal log + * @note Don't forget to initialize the frame delimiting protocol @see protocol.h + * + */ +void dIO_init(); -uint8_t register_var(void* ptr, uint16_t size, dio_type type, uint8_t writeable, char* name); -uint8_t register_var(void* ptr, uint16_t size, dio_type type, uint8_t writeable, char* name, float refresh_rate); -void start_group(char* groupname); +/** Registers a variable in the log. This function is usually called during program initalization + * All this data is stored in a descriptor that can be queried from master-side. + * @param ptr Pointer to the memory adress of the variable. Not extremely safe but that's all can be done with C + * @param size Size of the variable. Use sizeof(..) to always provide the right size. This will be improved when switching over C++ templated class + * @param type type of the variable. For a list of possible types @see dio_type + * @param writeable 0 if the variable is not writeable from master-side, 1 otherwise. + * @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. + * @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 + * @returns + 0 if everything ok + 1 if the internal log is full. + */ +uint8_t dIO_var(void* ptr, uint16_t size, dio_type type, uint8_t writeable, char* name, float refresh_rate = 0); -void distantio_decode(uint8_t* data,uint16_t datasize); +/** Starts a new group. Any subsequent call to @dio_var will register the variable under this new group. + * Groups also have descriptors that can be queried from master-side. + * @param groupname name of the variable group. + * + */ +void dIO_group(char* groupname); + +/** Decodes the contents of a new received frame. Frame of unvalid sizes or with unvalid CRCs are immediatly discarded. + * @param data pointer to the data buffer start adress + * @param datasize size in bytes of the data buffer + */ +void dIO_decode(uint8_t* data,uint16_t datasize); -// To call often -void update(float current_time); -void send_alive(); +/** Updates the internal state of DistantIO. Variables will be sent upon calling this method. + * 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. + * @note execution time of this function is directly related to the amount of registered variables, especially with small or 0 refresh rates. + * @param elapsed time since the beginning of the program + * + */ +void dIO_update(float current_time); + +/** Sends an alive signal to the master to signal the mbed device is running and communication is working. + * You should call this method approximately every half second. + * + */ +void dIO_send_alive(); #endif /* DISTANTIO_H_ */