--no commit message

Imanol-Mikel Barba Sabariego
1 parent 3813a6db
Showing 4 changed files with 99 additions and 19 deletions
Project/applications/smartcities/include/adc.h
Project/applications/smartcities/include/buffer.h
Project/applications/smartcities/include/i2c.h
Project/applications/smartcities/main.c
@@ -12,7 +12,6 @@
 #include "libwismart.h"
 #include "ch.h"
-
 #include "stm32f10x_gpio.h"
 #include "stm32f10x_adc.h"
+
+/**@file
+ * @brief Declaration for the internal buffer and memory management
+ * @author Maria Jorba Brosa
+ * @date 08/06/2014
+ *
+ * The functions declared in this file manage the I2C functionality of the device to use with the sensors
+ */
+
 #ifndef BUFFER_H
 #define BUFFER_H
 #include "libwismart.h"
 #include "json.h"
+//!Soft limit definition
+/*! This variable defines at which point the soft limit for used memory is reached. The specified value is used memory bytes. */
 #define SOFT_LIMIT      8192  /* en bytes -> 8k * 1024 */
+ //!Hard limit definition
+/*! This variable defines at which point the hard limit for used memory is reached. The specified value is used memory bytes.*/
 #define HARD_LIMIT     	10240
+
+//! Memory OK status definition
 #define	MEMORY_OK		0
+//! Soft limit status definition
 #define	SOFT_REACHED	1
+//! Hard limit status definition
 #define HARD_REACHED	2
+//! Debug printing definition
+/*! This definition is used for debugging purposes, it is a shorthand for printing debug information */
 #define DBG_BUFFER(fmt,...)                printf("%c[1;35mbuffer.c:%c[1;00m "fmt,0x1B,0x1B, ##__VA_ARGS__)
 //#define DBG_BUFFER(fmt,...)                printf("")
-char** put_message(char* info, char** buf,uint32_t *index, uint32_t *buf_len);
+//! Value write into buffer function
+/*! This function stores data into a memory buffer. It frees the memory of the old one, which is passed by argument, and returns a new one with the value stored. */
+char** put_message(char* info /*! Data to be stored */, char** buf /*! Old buffer */ ,uint32_t *index /*! Buffer index to store the data */, uint32_t *buf_len /*! Old buffer length */);
+
+//! Memory check function
+/*! This function checks the current used memory and returns the memory status definitions according to the amount of memory used. */
 int check_memory(void);
-int send(char** buf, uint32_t *index, uint32_t *size, char *provider_ID, char *sensor_ID);
-char** join_buf(char** buf, uint32_t *buf_len);
+
+//! Buffer data send function
+/*! This function sends the data in a specified buffer to the server. If successful, it frees the memory used by it. */
+int send(char** buf /*! Buffer to send */, uint32_t *index /*! Current buffer index */, uint32_t *size /*! Buffer size */, char *provider_ID /*! Current module ID */, char *sensor_ID /*! Sensor ID for the data stored in that buffer */);
+
+//! Buffer join function
+/*! This function returns a copy of the buffer passed by argument with one more slot to store another piece of data from the sensors */
+char** join_buf(char** buf /*! Old buffer */, uint32_t *buf_len /*! Old buffer length*/);
 #endif
 \ No newline at end of file
+
+/**@file
+ * @brief Declaration for the I2C functionality
+ * @author Imanol Barba Sabariego
+ * @date 08/06/2014
+ *
+ * The functions declared in this file manage the I2C functionality of the device to use with the sensors
+ */
+
 #ifndef I2C_H
 #define I2C_H
@@ -7,22 +16,54 @@
 #include "sensors.h"
 #include "libwismart.h"
+//! I2C Response timeout
+/*! This variable defines how many milliseconds will the device without obtaining answer from the bus until it considers that there is no I2C device in the address being polled. */
 #define I2C_TIMEOUT 100
+//! Debug printing definition
+/*! This definition is used for debugging purposes, it is a shorthand for printing debug information */
 #define DBG_I2C(fmt,...)                printf("%c[1;35mi2c.c:%c[1;00m "fmt,0x1B,0x1B, ##__VA_ARGS__)
 //#define DBG_I2C(fmt,...)                printf("")
-
+//! I2C initialization function
+/*! This function initializes the I2C bus in use for the sensors, which is I2C1, at a hardware level. */
 void I2C_init(void);
-void I2C_start(I2C_TypeDef* I2Cx, uint8_t address, uint8_t direction);
-void I2C_stop(I2C_TypeDef* I2Cx);
-void I2C_write(I2C_TypeDef* I2Cx, uint8_t data);
-uint8_t I2C_read_ack(I2C_TypeDef* I2Cx);
-uint8_t I2C_read_nack(I2C_TypeDef* I2Cx);
-void I2C_scan(I2C_TypeDef* I2Cx,uint8_t *addresses);
-uint8_t I2C_check(I2C_TypeDef* I2Cx, uint8_t address);
-void I2C_reset(I2C_TypeDef* I2Cx);
-void I2C_restart(I2C_TypeDef* I2Cx, uint8_t address, uint8_t direction);
+
+//! I2C comunication Start function
+/*! This function generates a START sequence in the I2C bus and sends the 7 bit address passed in the arguments along with the R/W bit. */
+void I2C_start(I2C_TypeDef* I2Cx /*! I2C device to use */, uint8_t address /*! I2C slave address */, uint8_t direction /*! R/W bit. Possible values are I2C_Direction_Transmitter and I2C_Direction_Receiver */);
+
+//! I2C communication Stop function
+/*! This function generaates a STOP sequence in the I2C bus, stopping the communication between master and slave */
+void I2C_stop(I2C_TypeDef* I2Cx /*! I2C device to use */);
+
+//! I2C write byte function
+/*! This function writes a byte into the bus using the specified I2C device */
+void I2C_write(I2C_TypeDef* I2Cx /*! I2C device to use */, uint8_t data /*! Byte to write */);
+
+//! I2C read byte function (with master ACK)
+/*! This function fetches a byte from the I2C bus that has been stored into the internal register and sends and ACK afterwards. */
+uint8_t I2C_read_ack(I2C_TypeDef* I2Cx /*! I2C device to use */);
+
+//! I2C read byte function (without master ACK)
+/*! This function fetches a byte from the I2C bus that has been stored into the internal register without sending and ACK afterwards. */
+uint8_t I2C_read_nack(I2C_TypeDef* I2Cx /*! I2C device to use */);
+
+//! I2C bus scan function
+/*! This function scans the I2C bus in search of known sensor addresses and returns them in the addresses array passed by argument. */
+void I2C_scan(I2C_TypeDef* I2Cx /*! I2C device to use */,uint8_t *addresses /*! Array to be filled */);
+
+//! I2C presence check function
+/*! This function checks a specified address to see if there are any slave devices listening. */
+uint8_t I2C_check(I2C_TypeDef* I2Cx /*! I2C device to use */, uint8_t address /*! Address to check */);
+
+//! I2C bus reset function
+/*! This function resets the I2C bus in case that a timeout occurred, pulling both lines up and resetting the internal registers to a known state. */
+void I2C_reset(I2C_TypeDef* I2Cx /*! I2C device to reset */);
+
+//! I2C communication repeated Start function
+/*! This function sends a repeated START sequence (a START sequence for which no previous STOP sequence was sent). */
+void I2C_restart(I2C_TypeDef* I2Cx /*! I2C device to use */, uint8_t address /*! I2C slave address */, uint8_t direction /*! R/W bit. Possible values are I2C_Direction_Transmitter and I2C_Direction_Receiver */);
 #endif
+
+/**@file
+ * @brief Main loop and global functions and variables
+ * @author Imanol Barba Sabariego, Ferràn Quer i Guerrero, Maria Jorba Brosa, Emilio Soca Herrera
+ * @date 08/06/2014
+ *
+ * This file holds the main function, which contains the main loop itself and necessary global functions and variables used to manage the state of the device.
+ */
+
 #include <string.h>
 #include "libwismart.h"
 #include "libwismart_irqs.h" /* implement irq handlers */
@@ -12,6 +21,7 @@
 #include "ntp.h"
 #include "sensors.h"
+//! Debug printing definition
 /*! This definition is used for debugging purposes, it is a shorthand for printing debug information */
 #define DBG(fmt,...)                printf("%c[1;35mmain.c:%c[1;00m "fmt,0x1B,0x1B, ##__VA_ARGS__)
 //#define DBG(fmt,...)              printf("")
@@ -52,7 +62,7 @@ void initLibwismart(void)
 //! NTP time update function
 /*! This function is called upon NTP update request and uses the methods declared in ntp.h to do so. */
-void update_time(unsigned long *time)
+void update_time(unsigned long *time /*! Variable to store the new time */)
 {
     do
     {
@@ -136,7 +146,7 @@ void init_registry(void)
 //! Function to send data to the server
 /*! This function sends all the data in the memory to the server */
-void send_data(char** buffers[], uint32_t ind[], uint32_t sizes[], uint8_t sensors[])
+void send_data(char** buffers[] /*! Array of in-memory buffers containing the data */, uint32_t ind[] /*! Buffer indexes */ , uint32_t sizes[] /*! Buffer sizes */, uint8_t sensors[] /*! Array of sensors addresses currently connected to the device */)
 {
     int j;
     for(j=0;j<sensors_length;j++)
@@ -150,7 +160,7 @@ void send_data(char** buffers[], uint32_t ind[], uint32_t sizes[], uint8_t senso
 //! Buffer data insertion function
 /*! This function inserts processed data in the memory */
-void put_buffers(char** buffers[],uint32_t ind[],uint32_t sizes[],char** cooked, uint8_t* sensors)
+void put_buffers(char** buffers[],/*! Array of in-memory buffers containing the data */, uint32_t ind[] /*! Buffer indexes */ , uint32_t sizes[] /*! Buffer sizes */,char** cooked /*! Array of processed data from the sensors */, uint8_t* sensors  /*! Array of sensors addresses currently connected to the device */)
 {
     DBG("Putting data in buffers...\r\n");
     int i;
@@ -168,7 +178,7 @@ void put_buffers(char** buffers[],uint32_t ind[],uint32_t sizes[],char** cooked,
 //! Data timestamping function
 /*! This function timestamps de collected data using the methods defined in ntp.h */
-char** timestamp_datas(char* value[],unsigned long timestamp, uint8_t* sensors)
+char** timestamp_datas(char* value[] /*! Raw data collected from the sensors */,unsigned long timestamp /* Current timestamp to add to the measurements*/, uint8_t* sensors /*! Array of sensors addresses currently connected to the device */)
 {
     DBG("Timestamping data...\r\n");
     char** cooked_data;
@@ -206,7 +216,7 @@ void wifi_connect(void)
 //! Battery reporting function
 /*! This function checks the battery level and sends it to the server */
-void send_battery_level(unsigned long timestamp)
+void send_battery_level(unsigned long timestamp /*! Current timestamp to add to the battery level measurement */)
 {
     DBG("Polling battery level...\r\n");
     char *batt_level = battery_value(get_battery_data());