Documentation finished

Imanol-Mikel Barba Sabariego
1 parent 3f393e23
Showing 3 changed files with 178 additions and 35 deletions
Project/applications/smartcities/include/httpClient.h
Project/applications/smartcities/include/ntp.h
Project/applications/smartcities/include/sensors.h
-/*
- * Custom http client implementation based on httpServer
+
+/**@file
+ * @brief Definition for the HTTP Client functions
+ * @author Ferràn Quer i Guerrero
+ * @date 08/06/2014
  *
+ * Custom http client implementation based on httpServer
  */
+
 #ifndef HTTP_CLIENT_H
 #define HTTP_CLIENT_H
@@ -14,39 +19,59 @@
 #include "ch.h"
 #include "globals.h"
-#define DEFAULT_REMOTE_IP  "147.83.2.135" // www.upc.edu
+//! Default remote port (HTTP)
 #define DEFAULT_REMOTE_PORT 80
+//! Endline definition
 #define ENDL "\r\n"
+//! Content-type header string
 #define CONTENT_TYPE_HEADER "Content-Type: application/json; charset=UTF-8"
+//! Debug printing definition
+/*! This definition is used for debugging purposes, it is a shorthand for printing debug information */
 #define DBG_HTTP(fmt,...)                printf("%c[1;35mhttpClient.c:%c[1;00m "fmt,0x1B,0x1B, ##__VA_ARGS__)
 //#define DBG_HTTP(fmt,...)                printf("")
-
+//! Available Request Methods
 typedef enum reqMethod
 {
+	//! POST request
 	post,
+	//! GET request
 	get,
+	//! PUT request
 	put,
+	//! DELETE request
 	del //delete may be a special word.
 }reqMethod;
+//! HTTP request header parameters
 typedef struct httpHeaders
 {
+	//! Request method
 	enum reqMethod method;
+	//! URI to send the request to
 	char* uri;
+	//! Size of the URI string
 	int uri_size;
+	//! HTTP host to send the request
 	char* host;
+	//! HTTP host string length
 	int host_size;
 }httpHeaders;
-
-int httpRequest(struct httpHeaders head, char* content, int content_size);
-const char* reqMethod2text(enum reqMethod method);
-char* int2string(int num);
-int numberofdigits(int number);
-int response2int(char* chars);
+//! HTTP Client request function
+/*! This function sends a HTTP request with the specified headers and content passed by argument. */
+int httpRequest(struct httpHeaders head /*! HTTP Header parameters */, char* content /*! Content to send */, int content_size /*! Content length */);
+//! Translates each request method from the enum to its string
+const char* reqMethod2text(enum reqMethod method /*! Method to translate */);
+//! Converts and returns an integer passed by argument as a string
+char* int2string(int num /*! Number to convert */);
+//! Calculates and returns the number of digits of a number passed by argument
+int numberofdigits(int number /*! Number to count */);
+//! HTTP response parsing function
+/*! This function parses the HTTP response and returns the HTTP response code. */
+int response2int(char* chars /*! HTTP response */);
 #endif
 \ No newline at end of file
+
+/**@file
+ * @brief Definition for the NTP functions
+ * @author Emilio Soca Herrera
+ * @date 08/06/2014
+ *
+ * The functions declared in this file manage the NTP functionality of the device to update local time and timestamp data
+ */
+
 #ifndef NTP_H
 #define NTP_H
@@ -18,29 +27,42 @@
 #include "ch.h"
 #include "globals.h"
+//! Debug printing definition
+/*! This definition is used for debugging purposes, it is a shorthand for printing debug information */
 #define DBG_NTP(fmt,...)                printf("%c[1;35mntp.c:%c[1;00m "fmt,0x1B,0x1B, ##__VA_ARGS__)
 //#define DBG_NTP(fmt,...)                printf("")
+//! Leap year calculation define
 #define LEAP_YEAR(Y) (((1970+Y)>0) && !((1970+Y)%4) && (((1970+Y)%100) || !((1970+Y)%400)))
+//! Length of NTP packet
 #define NTP_PACKET_LENGTH			48
+//! NTP Port
 #define SNTP_PORT                   123
-/** SNTP receive timeout - in milliseconds */
+//! SNTP receive timeout - in milliseconds
 #define SNTP_RECV_TIMEOUT           3000
-/** SNTP update delay - in milliseconds */
+//! SNTP update delay - in milliseconds
 #define SNTP_UPDATE_DELAY           60000
+//! Maximum packet length
 #define SNTP_MAX_DATA_LEN           48
+//! NTP receive time offset
 #define SNTP_RCV_TIME_OFS           32
 #define SNTP_LI_NO_WARNING          0x00
+//! NTP version specification
 #define SNTP_VERSION               (4/* NTP Version 4*/<<3)
+//! NTP Client mode definition
 #define SNTP_MODE_CLIENT            0x03
+//! NTP Server mode definition
 #define SNTP_MODE_SERVER            0x04
+//! NTP Broadcast mode definition
 #define SNTP_MODE_BROADCAST         0x05
+//! NTP Mask mode definition
 #define SNTP_MODE_MASK              0x07
-/* number of seconds between 1900 and 1970 */
+//! Number of seconds between 1900 and 1970
 #define DIFF_SEC_1900_1970         (2208988800LL)
-/*timezone from GMT*/
+//! Timezone from GMT
 #define TIME_ZONE					2
+//! Date structure definition
 typedef struct {
 	int second;
 	int minute;
@@ -50,10 +72,13 @@ typedef struct {
 	int year;
 }Date;
-char* timestamp_data(char* value,Date time);
+//! Data timestamping function
+/*! Adds a timestamp to the data passed by argument and returns a new string with the data timestamped .*/
+char* timestamp_data(char* value /*! Data to timestamp */,Date time /*! Timestamp */);
+//! This function returns the number of seconds since 1900 
 unsigned long getSecsSince1900(void);
-Date getDate(unsigned long);
-void udpNtp_test(void);
-
+//! Timestamp to Date converting function
+/*! This function converts a timestamp to a Date struct and returns the resulting struct. */
+Date getDate(unsigned long secsSince1900/*! Timestamp to convert */);
 #endif
+
+/**@file
+ * @brief Definition for the sensors and sensor related functions
+ * @author Imanol Barba Sabariego
+ * @date 08/06/2014
+ *
+ * Here are the sensor definitions and all the functions needed to fetch and parse data from the sensors.
+ * <br> REMEMBER TO UPDATE I2C SENSORS IN SENSOR DEFINITIONS IN THIS HEADER AND IN sensors.c WITH EACH NEW SENSOR!!!!
+ */
+
 #ifndef SENSORS_H
 #define SENSORS_H
@@ -8,28 +18,55 @@
 #include "module.h"
 #include "adc.h"
+//! Light sensor I2C address
 #define		LIGHT_ADDR			0x39
+//! Distance sensor I2C address
 #define		DISTANCE_ADDR		0x01
+//! Pressure sensor I2C address
 #define		PRESSURE_ADDR		0x77
+//! Humidity and temperature sensor I2C address
 #define		HUMIDITY_TEMP_ADDR	0x27
+//! Sound sensor I2C address
 #define		SOUND_ADDR			0x48
+//! Total number of sensors programmed
+/*! This definition MUST be updated everytime a new sensor is programmed in this file. */
 #define		TOTAL_SENSORS		5
-//REMEMBER TO UPDATE collectData ROUTINE WITH EACH NEW SENSOR!!!!
-//REMEMBER TO UPDATE I2C sensors in sensor definitions in this header and sensors.c WITH EACH NEW SENSOR!!!!
-#define		BATTERY_ADDR		0x00 //SIEMPRE PRESENTE, NUNCA BUSCAR EN i2c_scan
+//! Battery I2C address
+/*! NOTE: This is not a valid I2C address, it serves as identification ID.<br> Never scan the I2C bus looking for this address nor include it in the TOTAL_SENSORS count, 
+ *  as it is assumed that the battery sensor is always present (even without a battery). */
+#define		BATTERY_ADDR		0x00 
+//! Debug printing definition
+/*! This definition is used for debugging purposes, it is a shorthand for printing debug information */
 #define DBG_SENSORS(fmt,...)                printf("%c[1;35msensors.c:%c[1;00m "fmt,0x1B,0x1B, ##__VA_ARGS__)
 //#define DBG_SENSORS(fmt,...)                printf("")
+//! Sensor information structure definition
 typedef struct {
+  //! Sensor ID
   uint8_t ID;
+  //! Sensor description
   char* description;
+  //! Sensor type
   char* type;
+  //! Unit of data measured
   char* unit;
 } sensor;
-void wakeup_sensors(uint8_t logic_address);
+//! Sensor power control function
+/*! This function powers sensors on and off through the GPIO pins and the logical address (NOT THE I2C address) passed by argument.
+ *  <br>This works using the logical address a a byte and assigning each of the bits as one of the control pins as the following scheme shows:
+ *  <br>b7 -> X
+ *  <br>b6 -> X
+ *  <br>b5 -> X
+ *  <br>b4 -> PA7
+ *  <br>b3 -> PA6
+ *  <br>b2 -> PA5
+ *  <br>b1 -> PA4
+ *  <br>b0 -> PA3
+ */
+void wakeup_sensors(uint8_t logic_address /*! Logical address to set on the pins */);
 //SENSOR DEFINITIONS
 extern sensor light_sensor;
@@ -44,20 +81,35 @@ extern sensor* sensors[TOTAL_SENSORS+1];
 //SENSOR FUNCTIONS
 //LIGHT SENSOR
+//! Light sensor intialization function
+/*! This function powers the light sensor on and sends commands to start the light measurement. */
 void init_light(void);
+//! Light sensor data acquisition function
+/*! This function returns the light data from both CH0 and CH1 channels from the sensors. The data is serialized as CH1:CH0 */
 uint32_t get_light_data(void);
+//! Light sensor ADC CH0 data fetch function
 uint16_t get_light_ch0(void);
+//! Light sensor ADC CH1 data fetch function
 uint16_t get_light_ch1(void);
-char* light_value(uint32_t light);
+//! Light sensor data parsing function
+/*! This function takes the light numeric value serialized in get_light_data and returns a string to be timestamped and sent to the server. */
+char* light_value(uint32_t light /*! Numeric value */);
 //ULTRASONIC SENSOR
+//! Distance sensor data acquisition function
+/*! This function returns the distance measurement done by the distance sensor. */
 uint16_t get_distance_data(void);
+//! Distance sensor intialization function
+/*! This function powers the distance sensor on and sends commands to start the distance measurement. */
 void init_ultrasound(void);
-char* distance_value(uint16_t distance);
+//! Distance sensor data parsing function
+/*! This function takes the distance numeric value from get_distance_data and returns a string to be timestamped and sent to the server. */
+char* distance_value(uint16_t distance /*! Numeric value */);
 //PRESSURE SENSOR
 typedef struct bmp085_callibration bmp085_callibration_t;
+//! Pressure sensor callibration parameters
 struct bmp085_callibration {
 	uint16_t AC1;
 	uint16_t AC2;
@@ -71,35 +123,76 @@ struct bmp085_callibration {
 	uint16_t MC;
 	uint16_t MD;
 };
-
+//! Pressure sensor intialization function
+/*! This function powers the pressure sensor on and sends commands to start the pressure measurement. */
 void init_pressure(void);
+//! Temperature measurement intialization function
+/*! This function powers the temperature measurement function from the pressure sensor on and sends commands to start the temperature measurement. */
 void init_pressure_temperature(void);
+//! Pressure sensor data acquisition function
+/*! This function returns the pressure measurement done by the pressure sensor. */
 uint16_t get_pressure_data(void);
+//! Temperature data acquisition from the pressure sensor function
+/*! This function returns the temperature measurement done by the pressure sensor. */
 uint16_t get_pressure_temperature_data(void);
-void get_pressure_callibration_data(bmp085_callibration_t *calib_data);
-char* callibration_pressure_data_csv(bmp085_callibration_t *parameters);
-char* pressure_value(uint16_t pressure,uint16_t temperature);
+//! Pressure sensor callibration parameters acquisition function
+/*! This function retrieves the callibration parameters from the pressure sensor and writes them in the struct passed by argument. */
+void get_pressure_callibration_data(bmp085_callibration_t *calib_data /*! Struct to write in the callibration parameters */);
+//! Pressure sensor callibration parameters serialization function
+/*! This function returns a string with the callibration parameters passed by argument serialized in the following way:
+ *  <br>AC1,AC2,AC3,AC4,AC5,AC6,B1,B2,MB,MC,MD
+ */
+char* callibration_pressure_data_csv(bmp085_callibration_t *parameters /*! Callibration parameters to serialize */);
+//! Pressure sensor data parsing function
+/*! This function takes the pressure and temperature numeric value from get_pressure_data and get_pressure_temperature_data and returns a string to be timestamped and sent to the server. 
+ * 	<br>NOTE: The data is serialized as Pressure_Value,Temperature_Value
+ * 	<br>NOTE 2: The temperature measurement is mandatory, as the temperature data is used to calculate the true atmospheric pressure from the data returned from the pressure sensor.
+ */
+char* pressure_value(uint16_t pressure /*! Numeric value */,uint16_t temperature /*! Numeric value */);
 //HUMIDITY AND TEMPERATURE SENSOR
-
+//! Temperature and humidity sensor intialization function
+/*! This function powers the temperature and humidity sensor on and sends commands to start the measurements. */
 void init_humidity_temp(void);
+//! Humidity data acquisition from the humidity and temperature sensor function
+/*! This function returns the humidity measurement done by the temperature and humidity sensor. */
 uint16_t get_humidity_data(void);
+//! Temperature data acquisition from the temperature and humidity function
+/*! This function returns the temperature measurement done by the humidity and temperature sensor. */
 uint16_t get_temperature_data(void);
-char* temp_humidity_value(uint16_t temp, uint16_t humidity);
+//! Temperature and Humidity sensor data parsing function
+/*! This function takes the temperature and humidity numeric value from get_distance_data and get_humidity_data and returns a string to be timestamped and sent to the server. 
+ *  <br>NOTE: The data is serialized as Temperature_Value,Humidity_Value
+ */
+char* temp_humidity_value(uint16_t temp /*! Numeric value */, uint16_t humidity /*! Numeric value */);
 //SOUND SENSOR
-
+//! Sound sensor intialization function
+/*! This function intializes the sound ADC channel. */
 void init_sound(void);
+//! Sound ADC data sampling function
+/*! This function takes a sample from the sound ADC channel and returns the numeric value. */
 uint32_t get_sound_data(void);
-char* sound_value(uint32_t sound);
+//! Sound sensor data parsing function
+/*! This function takes the sound pressure level numeric value from get_battery_data and returns a string to be timestamped and sent to the server. */
+char* sound_value(uint32_t sound /*! Numeric value */);
 //BATTERY SENSOR
-
+//! Battery sensor intialization function.
+/*! This function intializes the battery ADC channel */
 void init_battery(void);
+//! Battery ADC data sampling function.
+/*! This function takes a sample from the battery ADC channel and returns the numeric value */
 uint32_t get_battery_data(void);
-char* battery_value(uint32_t battery);
+//! Battery sensor data parsing function
+/*! This function takes the battery level numeric value from get_battery_data and returns a string to be timestamped and sent to the server. */
+char* battery_value(uint32_t battery /*! Numeric value */);
 //Collect function
-void collectData(char* valueSensors[], uint8_t* sensors);
+//! Data fetching function
+/*! Polls every one of the currently connected sensors for data.
+ *  <br>NOTE: This routine is dependant on the sensors programmed and MUST be updated everytime a new sensor is programmed in this file. 
+ */
+void collectData(char* valueSensors[] /*! Output array for each one of the sensors that are passed by argument*/, uint8_t* sensors /*! Sensors where data has to be collected from */);
 #endif