DistantIO

Diff: distantio.h

Revision:

4:d675ad9c57ff

Parent:

3:135f55b5334e

Child:

5:e8936f38a338

--- 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_ */