From c32728ccbe13ee7bbcbf90a0b72a80a581abc37d Mon Sep 17 00:00:00 2001 From: adrien balleyguier Date: Wed, 6 May 2026 17:23:41 +0200 Subject: [PATCH] doc(nodes): adding comments in the nodes code close #62 --- nodes/src/ble_advertiser.c | 20 +++++++++++++------- nodes/src/ble_advertiser.h | 16 ++++++++++++++++ nodes/src/co2_level.c | 3 ++- nodes/src/co2_level.h | 14 ++++++++++++++ nodes/src/error_code.h | 11 ++++++----- nodes/src/hygrometer.c | 4 +++- nodes/src/hygrometer.h | 13 +++++++++++++ nodes/src/main.c | 1 + nodes/src/supervisor.c | 25 ++++++++++--------------- nodes/src/supervisor.h | 11 +++++++++++ nodes/src/thermometer.h | 13 +++++++++++++ nodes/src/window_status.h | 19 ++++++++++++++++--- 12 files changed, 118 insertions(+), 32 deletions(-) diff --git a/nodes/src/ble_advertiser.c b/nodes/src/ble_advertiser.c index be4a6a5..52951bf 100644 --- a/nodes/src/ble_advertiser.c +++ b/nodes/src/ble_advertiser.c @@ -2,6 +2,8 @@ static const int BT_MS_ADV_UP = 500; // [ms] time during which the advertising is active +// keys as defined in the specs +static const char BT_KEY_SIZE = 1; // [B] static const char BT_KEY_WINDOW = 0x01; static const char BT_KEY_HUMIDITY = 0x02; static const char BT_KEY_TEMP = 0x03; @@ -14,15 +16,19 @@ static const char BT_VALUE_SIZE_HUMIDITY = 1; static const char BT_VALUE_SIZE_TEMP = 2; static const char BT_VALUE_SIZE_CO2_LVL = 4; -static const int BT_AD_DATA_INDEX_WINDOW = BT_PREAMBLE_SIZE + 1; -static const int BT_AD_DATA_INDEX_HUMIDITY = BT_AD_DATA_INDEX_WINDOW + 2; -static const int BT_AD_DATA_INDEX_TEMP = BT_AD_DATA_INDEX_HUMIDITY + 2; -static const int BT_AD_DATA_INDEX_CO2_LVL = BT_AD_DATA_INDEX_TEMP + 3; +// value start index in the frame - equal to {prior field index + prior value size + key size} +static const int BT_AD_DATA_INDEX_WINDOW = BT_PREAMBLE_SIZE + BT_KEY_SIZE; +static const int BT_AD_DATA_INDEX_HUMIDITY = BT_AD_DATA_INDEX_WINDOW + BT_VALUE_SIZE_WINDOW + BT_KEY_SIZE; +static const int BT_AD_DATA_INDEX_TEMP = BT_AD_DATA_INDEX_HUMIDITY + BT_VALUE_SIZE_HUMIDITY + BT_KEY_SIZE; +static const int BT_AD_DATA_INDEX_CO2_LVL = BT_AD_DATA_INDEX_TEMP + BT_VALUE_SIZE_TEMP + BT_KEY_SIZE; -// sum of all value size + size for all keys +// sum of all value size + size for all keys + size preamble static const char BT_AD_TOTAL_SIZE = - BT_VALUE_SIZE_WINDOW + BT_VALUE_SIZE_HUMIDITY + BT_VALUE_SIZE_TEMP + BT_VALUE_SIZE_CO2_LVL + 4 + 2; + BT_PREAMBLE_SIZE + (4 * BT_KEY_SIZE) + + BT_VALUE_SIZE_WINDOW + BT_VALUE_SIZE_HUMIDITY + BT_VALUE_SIZE_TEMP + BT_VALUE_SIZE_CO2_LVL; +// data field in the broadcasted frame +// all values are set to 0 and the "company id" field is set to 0xffff static uint8_t ad_data[] = { 0xff, 0xff, BT_KEY_WINDOW, 0x00, @@ -30,6 +36,7 @@ static uint8_t ad_data[] = { BT_KEY_TEMP, 0x00, 0x00, BT_KEY_CO2_LVL, 0x00, 0x00, 0x00, 0x00 }; +// frame that will be broadcasted static const struct bt_data ad[] = { BT_DATA(BT_DATA_MANUFACTURER_DATA, ad_data, BT_AD_TOTAL_SIZE), }; @@ -46,7 +53,6 @@ enum error_code ble_advertise( ){ enum error_code ret = write_failed; int shift = 0; - // set values here ad_data[BT_AD_DATA_INDEX_WINDOW] = (uint8_t)(window_value == open ? 0x1 : 0x0); ad_data[BT_AD_DATA_INDEX_HUMIDITY] = (uint8_t)(hygro_value & 0xff); for(int i=0;i +// enum of all error code that may occur during the plein_de_eeeeeeeeeeeeeee application runtime enum error_code{ - success = 0, - init_failed, - read_failed, - write_failed, - error_unknown, + success = 0, // any kind of success + init_failed, // error related to initialization + read_failed, // error related to reading action + write_failed, // error related to writing action + error_unknown, // any error not linked to other code error_code_last, // iteration purpose }; diff --git a/nodes/src/hygrometer.c b/nodes/src/hygrometer.c index e30775c..67a5d55 100644 --- a/nodes/src/hygrometer.c +++ b/nodes/src/hygrometer.c @@ -13,7 +13,9 @@ enum error_code hygro_init(){ enum error_code hygro_get_value(int* holder){ enum error_code ret = read_failed; struct sensor_value humidity; - if( (sensor_sample_fetch(dev) >= 0) && + if( + // fetch is required to update sensor read data + (sensor_sample_fetch(dev) >= 0) && (sensor_channel_get(dev, SENSOR_CHAN_HUMIDITY, &humidity) >= 0) ){ *holder = humidity.val1; //taking only the integer part diff --git a/nodes/src/hygrometer.h b/nodes/src/hygrometer.h index 199ed94..4e09176 100644 --- a/nodes/src/hygrometer.h +++ b/nodes/src/hygrometer.h @@ -7,7 +7,20 @@ #include "error_code.h" +/** +* @brief init the hygrometer module +* @return init_failed upon any error during init +* @return success otherwise +*/ enum error_code hygro_init(); + +/** +* @brief Retrieve the humidity level and stores it in the given parameter +* @param[out] holder : pointer where the measurement will be stored +* @return read_failed upon any error occuring during measurement +* @return success otherwise +* @note the content of holder should not be trusted upon returning something else than success +*/ enum error_code hygro_get_value(int* holder); #endif //HYGROMETER_H diff --git a/nodes/src/main.c b/nodes/src/main.c index 899afdd..f9532f0 100644 --- a/nodes/src/main.c +++ b/nodes/src/main.c @@ -12,6 +12,7 @@ int main(void){ supervisor_init(); + // todo : sohuld init fail, activate led ? supervisor_run(); // should never come here return 0; diff --git a/nodes/src/supervisor.c b/nodes/src/supervisor.c index 50ef409..555d50f 100644 --- a/nodes/src/supervisor.c +++ b/nodes/src/supervisor.c @@ -6,18 +6,14 @@ const int SLEEP_MAX_DURATION = 30; // [min] enum error_code supervisor_init(){ enum error_code ret = init_failed; - ret = ble_init(); - if(success == ret){ - ret = co2_lvl_init(); - if(success == ret){ - ret = hygro_init(); - if(success == ret){ - ret = thermo_init(); - if(success == ret){ - ret = window_init(); - }else{} - }else{} - }else{} + if( + success == ble_init() && + success == co2_lvl_init() && + success == hygro_init() && + success == thermo_init() && + success == window_init() + ){ + ret = success; }else{} return ret; } @@ -34,14 +30,13 @@ enum error_code supervisor_run(){ hygro_status = hygro_get_value(&hygro_value); thermo_status = thermo_get_value(&thermo_value); window_status = window_get_value(&window_value); - // maybe change arguments order - // todo : manage special values + // todo : manage non-success error codes ble_advertise(window_value, hygro_value, thermo_value, co2_lvl_value); if((co2_lvl_value > CO2_LEVEL_EMPTY_ROOM) || (window_value == open)){ // there are people in the room, or someone forgot to close the window current_sleep_time = SLEEP_MIN_DURATION; }else{ - // no one is in the room, we can wait a liitle bit longer before getting the next data point + // no one is in the room, we can wait a litle bit longer before getting the next data point current_sleep_time += SLEEP_GRANULARITY; if(current_sleep_time > SLEEP_MAX_DURATION){ current_sleep_time = SLEEP_MAX_DURATION; diff --git a/nodes/src/supervisor.h b/nodes/src/supervisor.h index b705c3e..31a0658 100644 --- a/nodes/src/supervisor.h +++ b/nodes/src/supervisor.h @@ -15,7 +15,18 @@ extern const int SLEEP_GRANULARITY; // [min] extern const int SLEEP_MIN_DURATION; // [min] extern const int SLEEP_MAX_DURATION; // [min] +/** +* @brief init the supervisor, and thus the complete plein_de_ee application +* @return init_failed upon any error occurring during the initialisation of any module +* @return success otherwise +*/ enum error_code supervisor_init(); + +/** +* @brief exexcute the plein_de_eeeeeee application +* @return error_unknown +* @note should never return +*/ enum error_code supervisor_run(); #endif //SUPERVISOR_H diff --git a/nodes/src/thermometer.h b/nodes/src/thermometer.h index 37db431..c92eb5f 100644 --- a/nodes/src/thermometer.h +++ b/nodes/src/thermometer.h @@ -7,7 +7,20 @@ #include "error_code.h" +/** +* @brief init the thermometer module +* @return init_failed upon any error during init +* @return success otherwise +*/ enum error_code thermo_init(); + +/** +* @brief Retrieve the temperature and stores it in the given parameter +* @param[out] holder : pointer where the measurement will be stored +* @return read_failed upon any error occuring during measurement +* @return success otherwise +* @note the content of holder should not be trusted upon returning something else than success +*/ enum error_code thermo_get_value(int* holder); #endif //THERMOMETER_H diff --git a/nodes/src/window_status.h b/nodes/src/window_status.h index 401dfd7..b8fbde0 100644 --- a/nodes/src/window_status.h +++ b/nodes/src/window_status.h @@ -6,13 +6,26 @@ #include "error_code.h" enum window_status{ - closed = 0, - open, - unknown, + closed = 0, // window is closed or sensor is not connected + open, // window is opened + unknown, // window opening status could not be read windows_status_last, // iteration purpose }; +/** +* @brief init the window opening status module +* @return init_failed upon any error during init +* @return success otherwise +*/ enum error_code window_init(); + +/** +* @brief Retrieve the window opening status and stores it in the given parameter +* @param[out] holder : pointer where the measurement will be stored +* @return read_failed upon any error occuring during measurement +* @return success otherwise +* @note the content of holder should not be trusted upon returning something else than success +*/ enum error_code window_get_value(enum window_status* holder); #endif //WINDOW_STATUS_