From 27ff700c938e48bd88ca63575d65575150d9e842 Mon Sep 17 00:00:00 2001 From: Jeremy Tan Date: Sun, 3 Nov 2013 18:02:14 +0800 Subject: [PATCH] Update comments for Doxygen. Move old, unused files to the testing folder. --- server/Makefile | 1 + server/actuator.c | 16 +++++++-- server/bbb_pin.c | 1 + server/bbb_pin.h | 3 +- server/bbb_pin_defines.h | 6 ++-- server/common.h | 2 +- server/control.c | 33 +++++++++---------- server/control.h | 8 +++-- server/data.c | 2 +- server/data.h | 17 ++++------ server/fastcgi.c | 4 +-- server/fastcgi.h | 9 +++++ server/image.c | 10 +++++- server/image.h | 2 +- server/pin_test.c | 6 ++++ server/sensor.c | 15 +++++---- server/sensor.h | 2 +- testing/Camera/dilatometer/Readme.md | 1 + .../Camera/dilatometer}/dilatometer.c | 7 +++- .../Camera/dilatometer}/dilatometer.h | 0 .../Camera/dilatometer}/microscope.c | 0 .../Camera/dilatometer}/microscope.h | 0 .../Camera/dilatometer}/stream.c | 0 testing/interferometer/Readme.md | 1 + .../interferometer}/interferometer.c | 0 .../interferometer}/interferometer.h | 0 .../interferometer}/intertest.sh | 0 27 files changed, 95 insertions(+), 51 deletions(-) create mode 100644 testing/Camera/dilatometer/Readme.md rename {server => testing/Camera/dilatometer}/dilatometer.c (98%) rename {server => testing/Camera/dilatometer}/dilatometer.h (100%) rename {server => testing/Camera/dilatometer}/microscope.c (100%) rename {server => testing/Camera/dilatometer}/microscope.h (100%) rename {server => testing/Camera/dilatometer}/stream.c (100%) create mode 100644 testing/interferometer/Readme.md rename {server => testing/interferometer}/interferometer.c (100%) rename {server => testing/interferometer}/interferometer.h (100%) rename {server => testing/interferometer}/intertest.sh (100%) diff --git a/server/Makefile b/server/Makefile index 00ed880..10be3ec 100644 --- a/server/Makefile +++ b/server/Makefile @@ -28,6 +28,7 @@ microscope : microscope.o clean : make -C sensors clean + make -C actuators clean $(RM) $(BIN) $(BIN2) $(RM) *.o diff --git a/server/actuator.c b/server/actuator.c index 7473485..7716318 100644 --- a/server/actuator.c +++ b/server/actuator.c @@ -16,8 +16,12 @@ static Actuator g_actuators[ACTUATORS_MAX]; /** * Add and initialise an Actuator * @param name - Human readable name of the actuator - * @param read - Function to call whenever the actuator should be read + * @param user_id - Caller specified ID to be associated with this actuator + * @param set - Function to call whenever the actuator should be set * @param init - Function to call to initialise the actuator (may be NULL) + * @param cleanup - Function to call to deinitialise the actuator (may be NULL) + * @param sanity - Function to call to check that a user specified value is sane (may be NULL) + * @param initial_value - The initial value to set the actuator to * @returns Number of actuators added so far */ int Actuator_Add(const char * name, int user_id, SetFn set, InitFn init, CleanFn cleanup, SanityFn sanity, double initial_value) @@ -242,6 +246,7 @@ void Actuator_SetControl(Actuator * a, ActuatorControl * c) * Set an Actuator value * @param a - The Actuator * @param value - The value to set + * @param record - Whether or not to record the value to the Actuator's DataFile. */ void Actuator_SetValue(Actuator * a, double value, bool record) { @@ -275,8 +280,8 @@ void Actuator_SetValue(Actuator * a, double value, bool record) /** * Helper: Begin Actuator response in a given format * @param context - the FCGIContext + * @param a - the actuator to begin a response for * @param format - Format - * @param id - ID of Actuator */ void Actuator_BeginResponse(FCGIContext * context, Actuator * a, DataFormat format) { @@ -298,7 +303,7 @@ void Actuator_BeginResponse(FCGIContext * context, Actuator * a, DataFormat form /** * Helper: End Actuator response in a given format * @param context - the FCGIContext - * @param id - ID of the Actuator + * @param a - the actuator to end a response for * @param format - Format */ void Actuator_EndResponse(FCGIContext * context, Actuator * a, DataFormat format) @@ -458,6 +463,11 @@ Actuator * Actuator_Identify(const char * name) return NULL; } +/** + * Returns the last DataPoint that is currently available. + * @param id - The actuator ID for which to retrieve data from + * @return The last DataPoint + */ DataPoint Actuator_LastData(int id) { Actuator * a = &(g_actuators[id]); diff --git a/server/bbb_pin.c b/server/bbb_pin.c index bd31365..199706f 100644 --- a/server/bbb_pin.c +++ b/server/bbb_pin.c @@ -334,6 +334,7 @@ void ADC_Unexport(int pin) /** * Set a GPIO pin * @param pin - The pin to set. MUST have been exported before calling this function. + * @param value - The value to set the GPIO pin to. */ bool GPIO_Set(int pin, bool value) { diff --git a/server/bbb_pin.h b/server/bbb_pin.h index 658b95a..14bc7eb 100644 --- a/server/bbb_pin.h +++ b/server/bbb_pin.h @@ -31,6 +31,7 @@ extern bool PWM_Set(int pin, bool polarity, long period, long duty); // period a extern bool PWM_Stop(int pin); #else +//! @cond Doxygen_Suppress //Horrible hacks to silence gcc when compiling on systems that are not the BBB extern bool True_Stub(int arg, ...); extern bool ADC_Read_Stub(int *val, ...); @@ -53,7 +54,7 @@ extern bool GPIO_Read_Stub(bool *val, ...); #define PWM_Set(pin, polarity, period, duty) True_Stub((int)pin, polarity, period, duty) #define PWM_Stop(pin) True_Stub((int)pin) //yuck - +//! @endcond #endif //_BBB #endif //_BBB_PIN_H diff --git a/server/bbb_pin_defines.h b/server/bbb_pin_defines.h index cb77dac..7ccda87 100644 --- a/server/bbb_pin_defines.h +++ b/server/bbb_pin_defines.h @@ -10,7 +10,6 @@ #define BBB_PIN_COUNT 92 /** GPIO0 defines **/ - #define GPIO0_1 1 #define GPIO0_2 2 // Used for PWM #define GPIO0_3 3 // Used for PWM @@ -136,13 +135,16 @@ extern const unsigned char g_pin_index_to_gpio[GPIO_NUM_PINS]; #define ADC5 5 #define ADC6 6 #define ADC7 7 +/** The maximum voltage input to the ADC **/ #define ADC_VOLTAGE_MAX 1800 +/** The maximum raw value from the ADC **/ #define ADC_RAW_MAX (2 << ADC_BITS) +/** Converts the raw ADC value to a voltage in millivolts **/ #define ADC_TO_MVOLTS(x) ((double)((x)/2 << ADC_BITS) * (double)ADC_VOLTAGE_MAX) /** Number of ADC pins **/ #define ADC_NUM_PINS 8 - +/** The path to the ADCs on the BBB **/ #define ADC_DEVICE_PATH "/sys/bus/iio/devices/iio:device0/" /** PWM names to sysfs numbers **/ diff --git a/server/common.h b/server/common.h index 0875b34..5eee7cc 100644 --- a/server/common.h +++ b/server/common.h @@ -51,7 +51,7 @@ (tv)->tv_nsec = ((value) - (int)(value))*1e9; \ } -extern bool PathExists(const char * path); +//extern bool PathExists(const char * path); extern bool DirExists(const char * path); diff --git a/server/control.c b/server/control.c index f81ea00..280a132 100644 --- a/server/control.c +++ b/server/control.c @@ -11,17 +11,25 @@ #include #include +/** + * Control state information (start/stop/pause etc) + */ typedef struct ControlData { - ControlModes current_mode; - pthread_mutex_t mutex; - struct timespec start_time; - char user_name[31]; // The user who owns the currently running experiment - char experiment_dir[BUFSIZ]; //Directory for experiment - char experiment_name[BUFSIZ]; + ControlModes current_mode; /** Current experiment mode **/ + pthread_mutex_t mutex; /** Mutex to serialise access to control methods **/ + struct timespec start_time; /** Start time of current experiment **/ + char user_name[31]; /** The user who owns the currently running experiment **/ + char experiment_dir[BUFSIZ]; /** Directory for experiment **/ + char experiment_name[BUFSIZ]; /** Name of the current experiment **/ } ControlData; ControlData g_controls = {CONTROL_STOP, PTHREAD_MUTEX_INITIALIZER, {0}}; +/** + * Determines if a directory exists or not. + * @param path The path to check + * @return true iff the path exists + */ bool DirExists(const char *path) { DIR *dir = opendir(path); @@ -32,19 +40,9 @@ bool DirExists(const char *path) return false; } -bool PathExists(const char *path) -{ - FILE *fp = fopen(path, "r"); - if (fp) { - fclose(fp); - return true; - } - return false; -} - /** * Lists all experiments for the current user. - * @param The context to work in + * @param context The context to work in */ void ListExperiments(FCGIContext *context) { @@ -260,7 +258,6 @@ const char* Control_SetMode(ControlModes desired_mode, void * arg) /** * Gets a string representation of the current mode - * @param mode The mode to get a string representation of * @return The string representation of the mode */ const char * Control_GetModeName() { diff --git a/server/control.h b/server/control.h index 0dfdc47..e623033 100644 --- a/server/control.h +++ b/server/control.h @@ -5,6 +5,10 @@ #ifndef _CONTROL_H #define _CONTROL_H +/** + * The possible experiment control modes that the server can be in. + * At present, CONTROL_EMERGENCY largely does nothing. TODO: Fix this + */ typedef enum ControlModes { CONTROL_START, CONTROL_PAUSE, @@ -17,12 +21,12 @@ typedef enum ControlModes { #define INVALID_CHARACTERS "\"*/:<>?\\|. " /** The same as INVALID_CHARACTERS, except escaped for use in JSON strings **/ #define INVALID_CHARACTERS_JSON "\\\"*/:<>?\\\\|. " - +/** The username of a user with no authentication (DEBUG ONLY) **/ #define NOAUTH_USERNAME "_anonymous_noauth" extern void Control_Handler(FCGIContext *context, char *params); extern const char* Control_SetMode(ControlModes desired_mode, void * arg); -extern ControlModes Control_GetMode(); +//extern ControlModes Control_GetMode(); extern const char * Control_GetModeName(); //extern bool Control_Lock(); //extern void Control_Unlock(); diff --git a/server/data.c b/server/data.c index 19828bc..38eba83 100644 --- a/server/data.c +++ b/server/data.c @@ -292,7 +292,7 @@ int Data_FindByTime(DataFile * df, double time_stamp, DataPoint * closest) * @param df - DataFile to access * @param start - Info about start_time param * @param end - Info about end_time param - * @param fmt - Info about format param + * @param format - Info about format param * @param current_time - Current time */ void Data_Handler(DataFile * df, FCGIValue * start, FCGIValue * end, DataFormat format, double current_time) diff --git a/server/data.h b/server/data.h index 0573c2e..188f5aa 100644 --- a/server/data.h +++ b/server/data.h @@ -6,7 +6,7 @@ #ifndef _DATAPOINT_H #define _DATAPOINT_H -#define DATA_BUFSIZ 10 // Size to use for DataPoint buffers (TODO: Optimise) +#define DATA_BUFSIZ 10 /** Size to use for DataPoint buffers (TODO: Optimise) **/ #include "common.h" @@ -23,8 +23,8 @@ typedef struct /** Enum of output format types for DataPoints **/ typedef enum { - JSON, // JSON data - TSV // Tab seperated vector + JSON, /** JSON data */ + TSV /** Tab seperated vector */ } DataFormat; /** @@ -34,10 +34,10 @@ typedef enum */ typedef struct { - FILE * file; // file pointer - int num_points; // Number of DataPoints in the file - char * filename; // Name of the file - pthread_mutex_t mutex; // Mutex around num_points + FILE * file; /** file pointer */ + int num_points; /** Number of DataPoints in the file */ + char * filename; /** Name of the file */ + pthread_mutex_t mutex; /** Mutex around num_points */ } DataFile; @@ -54,7 +54,4 @@ extern double Data_Calibrate(double value, double x[], double y[], int size); extern void Data_Handler(DataFile * df, FCGIValue * start, FCGIValue * end, DataFormat format, double current_time); // Helper; given FCGI params print data extern DataFormat Data_GetFormat(FCGIValue * fmt); // Helper; convert human readable format string to DataFormat - -extern double Data_Callibrate(double value, double map[], int map_size); - #endif //_DATAPOINT_H diff --git a/server/fastcgi.c b/server/fastcgi.c index 9ff3acc..6006322 100644 --- a/server/fastcgi.c +++ b/server/fastcgi.c @@ -164,7 +164,6 @@ bool FCGI_LockControl(FCGIContext *context, const char * user_name, UserType use * the key) has control or not. If validated, the context control_timestamp is * updated. * @param context The context to work in - * @param key The control key to be validated. * @return TRUE if authorized, FALSE if not. */ bool FCGI_HasControl(FCGIContext *context) @@ -386,7 +385,6 @@ void FCGI_BeginJSON(FCGIContext *context, StatusCodes status_code) * Generic accept response in JSON format. * @param context The context to work in * @param description A short description. - * @param cookie Optional. If given, the cookie field is set to that value. */ void FCGI_AcceptJSON(FCGIContext *context, const char *description) { @@ -510,7 +508,7 @@ void FCGI_WriteBinary(void * data, size_t size, size_t num_elem) /** * Escapes a string so it can be used safely. * Currently escapes to ensure the validity for use as a JSON string - * Does not support unicode specifiers in the form of \uXXXX. + * Does not support unicode specifiers in the form of \\uXXXX. * @param buf The string to be escaped * @return The escaped string (return value == buf) */ diff --git a/server/fastcgi.h b/server/fastcgi.h index a417a43..09884d1 100644 --- a/server/fastcgi.h +++ b/server/fastcgi.h @@ -35,12 +35,20 @@ typedef enum StatusCodes { #define CONTROL_KEY_BUFSIZ 41 +/** + * An entry that describes an expected user parameter for parsing. + * To be used in conjunction with @see FCGI_ParseRequest. + */ typedef struct FCGIValue { + /** The name of the key (from key/value pair) [in] **/ const char *key; + /** A pointer to a variable that will hold the parsed value [out] **/ void *value; + /** Bit flags that determine things like if the field is required and if it was received [in/out] **/ unsigned flags; } FCGIValue; +/** The type of a user (unauthorised, normal, admin). **/ typedef enum {USER_UNAUTH, USER_NORMAL, USER_ADMIN} UserType; /**Contextual information related to FCGI requests*/ @@ -66,6 +74,7 @@ typedef struct int response_number; } FCGIContext; +/** The type definition of a module handler. **/ typedef void (*ModuleHandler) (FCGIContext *context, char *params); extern bool FCGI_LockControl(FCGIContext *context, const char * user_name, UserType user_type); diff --git a/server/image.c b/server/image.c index dcc122d..0e4ff48 100644 --- a/server/image.c +++ b/server/image.c @@ -8,6 +8,11 @@ static CvCapture * g_capture = NULL; static int g_captureID = -1; +/** + * Image stream handler. Returns an image to the user. + * @param context The context to work in + * @param params User specified parameters + */ void Image_Handler(FCGIContext * context, char * params) { @@ -53,7 +58,7 @@ void Image_Handler(FCGIContext * context, char * params) * @param num - Camera id * @param width - Width to force * @param height - Height to force - * @param image - Pointer to CvMat* to set with result + * @param frame - Pointer to IplImage* to set with result * @returns true on success, false on error */ bool Camera_GetImage(int num, int width, int height, IplImage ** frame) @@ -97,6 +102,9 @@ void Image_Handler(FCGIContext * context, char * params) return result; } +/** + * Executed on cleanup. Releases the OpenCV Capture structs. + */ void Image_Cleanup() { // Release the capture and IplImage pointers diff --git a/server/image.h b/server/image.h index 8e2cd68..9074e85 100644 --- a/server/image.h +++ b/server/image.h @@ -9,7 +9,7 @@ #include "common.h" #include "cv.h" -extern void Image_Init(); +//extern void Image_Init(); extern void Image_Handler(FCGIContext * context, char * params); extern void Image_Cleanup(); extern bool Camera_GetImage(int num, int width, int height, IplImage ** image); diff --git a/server/pin_test.c b/server/pin_test.c index 77c0ef9..8640a60 100644 --- a/server/pin_test.c +++ b/server/pin_test.c @@ -30,6 +30,12 @@ void Pin_Close() PWM_Unexport(i); } +/** + * Configures a pin (Export/Unexport business) + * @param type The pin type (GPIO/PWM/ADC) + * @param pin_export Whether to export/unexport/leave-as-is the pin + * @param num The pin number + */ bool Pin_Configure(const char *type, int pin_export, int num) { bool ret = true; diff --git a/server/sensor.c b/server/sensor.c index 4e8ac7f..3919a19 100644 --- a/server/sensor.c +++ b/server/sensor.c @@ -23,10 +23,8 @@ int g_num_sensors = 0; * @param user_id - User identifier * @param read - Function to call whenever the sensor should be read * @param init - Function to call to initialise the sensor (may be NULL) - * @param max_error - Maximum error threshold; program will exit if this is exceeded for the sensor reading - * @param min_error - Minimum error threshold; program will exit if the sensor reading falls below this value - * @param max_warn - Maximum warning threshold; program will log warnings if the value exceeds this threshold - * @param min_warn - Minimum warning threshold; program will log warnings if the value falls below this threshold + * @param cleanup - Function to call whenever to deinitialise the sensor (may be NULL) + * @param sanity - Function to call to check that the sensor value is sane (may be NULL) * @returns Number of actuators added so far */ int Sensor_Add(const char * name, int user_id, ReadFn read, InitFn init, CleanFn cleanup, SanityFn sanity) @@ -277,7 +275,7 @@ Sensor * Sensor_Identify(const char * name) /** * Helper: Begin sensor response in a given format * @param context - the FCGIContext - * @param id - ID of sensor + * @param s - Sensor to begin the response for * @param format - Format */ void Sensor_BeginResponse(FCGIContext * context, Sensor * s, DataFormat format) @@ -300,7 +298,7 @@ void Sensor_BeginResponse(FCGIContext * context, Sensor * s, DataFormat format) /** * Helper: End sensor response in a given format * @param context - the FCGIContext - * @param id - ID of the sensor + * @param s - Sensor to end the response for * @param format - Format */ void Sensor_EndResponse(FCGIContext * context, Sensor * s, DataFormat format) @@ -424,6 +422,11 @@ const char * Sensor_GetName(int id) return g_sensors[id].name; } +/** + * Returns the last DataPoint that is currently available. + * @param id - The sensor ID for which to retrieve data from + * @return The last DataPoint + */ DataPoint Sensor_LastData(int id) { Sensor * s = &(g_sensors[id]); diff --git a/server/sensor.h b/server/sensor.h index 3de48e0..b2bb63c 100644 --- a/server/sensor.h +++ b/server/sensor.h @@ -80,7 +80,7 @@ extern void Sensor_SetModeAll(ControlModes mode, void * arg); extern void Sensor_SetMode(Sensor * s, ControlModes mode, void * arg); extern void * Sensor_Loop(void * args); // Main loop for a thread that handles a Sensor -extern bool Sensor_Read(Sensor * s, DataPoint * d); // Read a single DataPoint, indicating if it has changed since the last one +//extern bool Sensor_Read(Sensor * s, DataPoint * d); // Read a single DataPoint, indicating if it has changed since the last one extern Sensor * Sensor_Identify(const char * str); // Identify a Sensor from a string extern void Sensor_Handler(FCGIContext *context, char * params); // Handle a FCGI request for Sensor data diff --git a/testing/Camera/dilatometer/Readme.md b/testing/Camera/dilatometer/Readme.md new file mode 100644 index 0000000..231dd69 --- /dev/null +++ b/testing/Camera/dilatometer/Readme.md @@ -0,0 +1 @@ +The files here are the previous versions of camera/dilatometer/microscope code that once resided in the main `server` folder. They are now placed here because they are no longer in use. diff --git a/server/dilatometer.c b/testing/Camera/dilatometer/dilatometer.c similarity index 98% rename from server/dilatometer.c rename to testing/Camera/dilatometer/dilatometer.c index 83cdc4c..7a85878 100644 --- a/server/dilatometer.c +++ b/testing/Camera/dilatometer/dilatometer.c @@ -119,6 +119,9 @@ static bool Dilatometer_GetImage() return result; } +/** + * Applies the Canny threshold algorithm to the captured image. + */ void CannyThreshold() { if ( g_edges == NULL) @@ -240,7 +243,9 @@ void Dilatometer_Init() Dilatometer_GetEdge(&val, 1); } -// Overlays a line over the given edge position +/** + * Overlays a line over the given edge position + */ void Draw_Edge(double edge) { CvScalar value; diff --git a/server/dilatometer.h b/testing/Camera/dilatometer/dilatometer.h similarity index 100% rename from server/dilatometer.h rename to testing/Camera/dilatometer/dilatometer.h diff --git a/server/microscope.c b/testing/Camera/dilatometer/microscope.c similarity index 100% rename from server/microscope.c rename to testing/Camera/dilatometer/microscope.c diff --git a/server/microscope.h b/testing/Camera/dilatometer/microscope.h similarity index 100% rename from server/microscope.h rename to testing/Camera/dilatometer/microscope.h diff --git a/server/stream.c b/testing/Camera/dilatometer/stream.c similarity index 100% rename from server/stream.c rename to testing/Camera/dilatometer/stream.c diff --git a/testing/interferometer/Readme.md b/testing/interferometer/Readme.md new file mode 100644 index 0000000..1692725 --- /dev/null +++ b/testing/interferometer/Readme.md @@ -0,0 +1 @@ +These are the interferometer test files, which once resided in the main `server` directory. They have been moved here because this code is no longer in use. diff --git a/server/interferometer.c b/testing/interferometer/interferometer.c similarity index 100% rename from server/interferometer.c rename to testing/interferometer/interferometer.c diff --git a/server/interferometer.h b/testing/interferometer/interferometer.h similarity index 100% rename from server/interferometer.h rename to testing/interferometer/interferometer.h diff --git a/server/intertest.sh b/testing/interferometer/intertest.sh similarity index 100% rename from server/intertest.sh rename to testing/interferometer/intertest.sh -- 2.20.1