Revision 4:d675ad9c57ff, committed 2015-10-13

Comitter:

Overdrivr

Date:

Tue Oct 13 12:20:44 2015 +0000

Parent:

3:135f55b5334e

Child:

5:e8936f38a338

Commit message:

Interface cleanup + added documentation

Changed in this revision

--- a/distantio.cpp	Mon Oct 12 13:29:40 2015 +0000
+++ b/distantio.cpp	Tue Oct 13 12:20:44 2015 +0000
@@ -18,15 +18,13 @@
 static log Log;
 uint32_t tmp;
 
-void send_variable(uint16_t index,float extra_identifier_1,uint16_t extra_identifier_2=0);
-uint16_t get_size(dio_type type);
-void send_descriptor(uint16_t index);
-void send_group_descriptor(uint16_t index);
+void _dIO_send_variable(uint16_t index,float extra_identifier_1,uint16_t extra_identifier_2=0);
+uint16_t _dIO_get_size(dio_type type);
+void _dIO_send_descriptor(uint16_t index);
+void _dIO_send_group_descriptor(uint16_t index);
 
-/**
- * Inits the distant io framework
- */
-void init_distantio()
+
+void dIO_init()
 {
 	uint16_t i;
 	char default_name[] = {"undef.  "};
@@ -46,17 +44,14 @@
 	strncpy(Log.groups[0].name,"default",NAMESIZE);
 }
 
-/**
- * Register a variable exchanged with the computer
- */
-uint8_t register_var(void* ptr, uint16_t size, dio_type type, uint8_t writeable, char* name, float refresh_rate)
+uint8_t dIO_var(void* ptr, uint16_t size, dio_type type, uint8_t writeable, char* name, float refresh_rate)
 {
 	// Too many variables, aborting
 	if(Log.amount >= VARIABLES_AMOUNT)
 		return 1;
 
 	Log.variables[Log.amount].ptr = (uint8_t*) ptr;
-	Log.variables[Log.amount].size = get_size(type);
+	Log.variables[Log.amount].size = _dIO_get_size(type);
 	Log.variables[Log.amount].writeable = writeable;
 	Log.variables[Log.amount].type = type;
 	Log.variables[Log.amount].groupID = Log.current_group_id;
@@ -68,22 +63,124 @@
 	return 0;
 }
 
-uint8_t register_var(void* ptr, uint16_t size, dio_type type, uint8_t writeable, char* name)
-{
-	register_var(ptr,size,type,writeable,name,0.f);
-}
-
-void start_group(char* groupname)
+void dIO_group(char* groupname)
 {
 	Log.current_group_id++;
 	strncpy(Log.groups[Log.current_group_id].name,groupname,NAMESIZE);
 }
 
-/**
- * Send var descriptor
- */
+
+
+void dIO_decode(uint8_t* data,uint16_t datasize)
+{
+	// First check data size
+	if(datasize != FRAMESIZE)
+		return;
+
+	// Second, check CRC
+	uint16_t crc_value = crc16(data,FRAMESIZE-2);
+	uint16_t crc_rx = ((uint16_t)data[FRAMESIZE-2] << 8) | data[FRAMESIZE-1];
+
+	if(crc_value != crc_rx)
+		return;
+	
+	// Process frame
+	// First, identify command
+	uint8_t command = data[0];
+	
+	// Second, identify variable ID
+	uint16_t ID = data[2] + (data[1] << 8);
+	ID = (ID & 0x3FF);
+	
+	// Third, identify data type
+	uint8_t type = data[3];
+
+	switch(command)
+	{
+		// User requested descriptors
+		case 0x02:
+			// Send variables
+			for(uint16_t i = 0 ; i < Log.amount ; i++)
+				_dIO_send_descriptor(i);
+			// Send groups
+			for(uint16_t i = 0 ; i <= Log.current_group_id ; i++)
+				_dIO_send_group_descriptor(i);
+			break;
+
+		// User provided value to write
+		case 0x04:
+			if(ID >= Log.amount)
+				return;
+
+			if(Log.variables[ID].writeable == 0x00)
+				return;
+
+			if(Log.variables[ID].type != type)
+				return;
+
+			uint16_t start_address = DATASTART + DATASIZE - 1;
 
-void send_descriptor(uint16_t index)
+			// Copy contents directly into variable
+			for(uint16_t i = 0 ; i < Log.variables[ID].size ; i++)
+			{
+				// Packet is big-endian, convert to little-endian
+				uint8_t offset = start_address - i;
+				*(Log.variables[ID].ptr + i) = *(data + offset);
+			}
+			break;
+
+		// User requested variable read
+		case 0x05:
+			if(ID >= Log.amount)
+				return;
+
+			Log.variables[ID].send = 1;
+			break;
+
+		// User requested stop variable read
+		case 0x06:
+			if(ID >= Log.amount)
+				return;
+			Log.variables[ID].send = 0;
+			break;
+		
+	}
+}
+
+void dIO_update(float current_time)
+{
+	for(uint16_t i = 0 ; i < Log.amount ; i++)
+	{
+		if(Log.variables[i].send == 0)
+			continue;
+		
+		if(current_time < Log.variables[i].last_refreshed + Log.variables[i].refresh_rate)
+			continue;
+			
+		_dIO_send_variable(i,current_time);
+		Log.variables[i].last_refreshed = current_time;
+	}
+}
+
+void dIO_send_alive()
+{
+	static uint8_t buffer[FRAMESIZE];
+	buffer[0] = 0x03;
+	 
+	// Compute crc
+	uint16_t crc_value = crc16(buffer,FRAMESIZE - 2);
+
+	// Write crc into buffer's last byte
+	buffer[FRAMESIZE - 1] = crc_value & 0xFF;
+	buffer[FRAMESIZE - 2] = (crc_value >> 8) & 0xFF;
+
+	// Send frame to encoding
+	encode(buffer,FRAMESIZE);
+}
+
+/* ------------------- PRIVATE FUNCTIONS ------------------ */
+
+void _dIO_send_descriptor(uint16_t index)
 {
 	if(index >= Log.amount)
 		return;
@@ -134,7 +231,7 @@
 	encode(buffer,i);
 }
 
-void send_group_descriptor(uint16_t index)
+void _dIO_send_group_descriptor(uint16_t index)
 {
 	if(index > Log.current_group_id)
 		return;
@@ -177,98 +274,8 @@
 	encode(buffer,i);
 }
 
-void distantio_decode(uint8_t* data,uint16_t datasize)
-{
-	// First check data size
-	if(datasize != FRAMESIZE)
-		return;
 
-	// Second, check CRC
-	uint16_t crc_value = crc16(data,FRAMESIZE-2);
-	uint16_t crc_rx = ((uint16_t)data[FRAMESIZE-2] << 8) | data[FRAMESIZE-1];
-
-	if(crc_value != crc_rx)
-		return;
-	
-	// Process frame
-	// First, identify command
-	uint8_t command = data[0];
-	
-	// Second, identify variable ID
-	uint16_t ID = data[2] + (data[1] << 8);
-	ID = (ID & 0x3FF);
-	
-	// Third, identify data type
-	uint8_t type = data[3];
-
-	switch(command)
-	{
-		// User requested descriptors
-		case 0x02:
-			// Send variables
-			for(uint16_t i = 0 ; i < Log.amount ; i++)
-				send_descriptor(i);
-			// Send groups
-			for(uint16_t i = 0 ; i <= Log.current_group_id ; i++)
-				send_group_descriptor(i);
-			break;
-
-		// User provided value to write
-		case 0x04:
-			if(ID >= Log.amount)
-				return;
-
-			if(Log.variables[ID].writeable == 0x00)
-				return;
-
-			if(Log.variables[ID].type != type)
-				return;
-
-			uint16_t start_address = DATASTART + DATASIZE - 1;
-
-			// Copy contents directly into variable
-			for(uint16_t i = 0 ; i < Log.variables[ID].size ; i++)
-			{
-				// Packet is big-endian, convert to little-endian
-				uint8_t offset = start_address - i;
-				*(Log.variables[ID].ptr + i) = *(data + offset);
-			}
-			break;
-
-		// User requested variable read
-		case 0x05:
-			if(ID >= Log.amount)
-				return;
-
-			Log.variables[ID].send = 1;
-			break;
-
-		// User requested stop variable read
-		case 0x06:
-			if(ID >= Log.amount)
-				return;
-			Log.variables[ID].send = 0;
-			break;
-		
-	}
-}
-
-void update(float current_time)
-{
-	for(uint16_t i = 0 ; i < Log.amount ; i++)
-	{
-		if(Log.variables[i].send == 0)
-			continue;
-		
-		if(current_time < Log.variables[i].last_refreshed + Log.variables[i].refresh_rate)
-			continue;
-			
-		send_variable(i,current_time);
-		Log.variables[i].last_refreshed = current_time;
-	}
-}
-
-void send_variable(uint16_t index,float extra_identifier_1,uint16_t extra_identifier_2)
+void _dIO_send_variable(uint16_t index,float extra_identifier_1,uint16_t extra_identifier_2)
 {
 	if(index >= Log.amount)
 		return;
@@ -331,28 +338,8 @@
 	encode(buffer,i);
 }
 
-void send_alive()
-{
-	static uint8_t buffer[FRAMESIZE];
-	buffer[0] = 0x03;
-	 
-	// Compute crc
-	uint16_t crc_value = crc16(buffer,FRAMESIZE - 2);
 
-	// Write crc into buffer's last byte
-	buffer[FRAMESIZE - 1] = crc_value & 0xFF;
-	buffer[FRAMESIZE - 2] = (crc_value >> 8) & 0xFF;
-
-	// Send frame to encoding
-	encode(buffer,FRAMESIZE);
-}
-
-
-/**
- * Returns the size in byte for each variable
- */
-
-uint16_t get_size(dio_type type)
+uint16_t _dIO_get_size(dio_type type)
 {
 	switch(type)
 	{

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