From 123653cc037038a3011bec4f37067677104fe07c Mon Sep 17 00:00:00 2001 From: joran2738 <101818067+joran2738@users.noreply.github.com> Date: Thu, 9 Nov 2023 19:36:13 +0100 Subject: [PATCH] adding comments --- project/Core/Inc/UDP_broadcast.h | 35 +++++--- project/Core/Src/UDP_broadcast.c | 150 ++++++++++++++++++------------- 2 files changed, 110 insertions(+), 75 deletions(-) diff --git a/project/Core/Inc/UDP_broadcast.h b/project/Core/Inc/UDP_broadcast.h index 65ac3be..bfbe66d 100644 --- a/project/Core/Inc/UDP_broadcast.h +++ b/project/Core/Inc/UDP_broadcast.h @@ -8,6 +8,7 @@ #ifndef INC_UDP_BROADCAST_H_ #define INC_UDP_BROADCAST_H_ +// includes #include #include #include @@ -16,16 +17,26 @@ #define LOGGER_LEVEL_ALL #include "log.h" -#define sod_name "set_owner_details_name" -#define god_name "get_owner_details_name" -#define sod_surname "set_owner_details_surname" -#define god_surname "get_owner_details_surname" -#define sod_reply "set_owner_details_reply" -#define god_reply "get_owner_details_reply" -#define sod_mac "set_owner_details_mac" -#define sod "set_owner_details" -#define f_reply "format_reply" +// Defines used by owner details error handler +#define SOD_NAME "set_owner_details_name" +#define GOD_NAME "get_owner_details_name" +#define SOD_SURNAME "set_owner_details_surname" +#define GOD_SURNAME "get_owner_details_surname" +#define SOD_REPLY "set_owner_details_reply" +#define GOD_REPLY "get_owner_details_reply" +#define SOD_MAC "set_owner_details_mac" +#define SOD "set_owner_details" +#define F_REPLY "format_reply" +// Defines used by UDP callback +#define MAX_DATA_SIZE 50 // Define the maximum expected data size +#define UDP_QUESTION1 "Where are you?v1.0" + +/** + * @struct owner_details_t + * @brief contains information about the owner + * + */ typedef struct { char name[20]; @@ -34,16 +45,14 @@ typedef struct { char reply[100]; }owner_details_t; +// The following functions are used for owner details (those that must be available in main) uint8_t set_owner_details(owner_details_t*, char* , char*); char* get_owner_details_name(owner_details_t*); char* get_owner_details_surname(owner_details_t*); char* get_owner_details_reply(owner_details_t*); +// The following functions are used for UDP (those that must be available in main) err_t init_UDP_server(); - - - - #endif /* INC_UDP_BROADCAST_H_ */ diff --git a/project/Core/Src/UDP_broadcast.c b/project/Core/Src/UDP_broadcast.c index b57a60b..fcc699e 100644 --- a/project/Core/Src/UDP_broadcast.c +++ b/project/Core/Src/UDP_broadcast.c @@ -5,18 +5,23 @@ * Author: joran */ //| + +// Includes #include "UDP_broadcast.h" -static const char *TAG = "UDP_broadcast"; -static char reply_str[100] = "|no reply formatted yet|"; +static const char *TAG = "UDP_broadcast"; // Tag used in logs +static char reply_str[100] = "|no reply formatted yet|"; // Global reply string for UDP broadcast /** * @fn void owner_details_error_handler(owner_details_t*, char*, char*) - * @brief + * @brief owner_details_error_handler() is called when one of the owner details functions had an error + * it checks which of the parameters in the function where the error occured, is a NULL pointer + * and logs a warning depending on that * - * @param owner - * @param word - * @param funct + * + * @param owner owner_details_t structure, it contains information about the owner + * @param word string parameter that was used in the function that triggered this handler + * @param funct name of the function where the error occured */ static void owner_details_error_handler(owner_details_t* owner, char* funct,char* word){ @@ -33,22 +38,25 @@ static void owner_details_error_handler(owner_details_t* owner, char* funct,char /** * @fn uint8_t set_owner_details_mac(owner_details_t*) - * @brief + * @brief set_owner_details_mac() gets the MAC address from the default netif + * and sets it in the owner_details_t struct * - * @param owner - * @return + * @param owner owner_details_t structure, it contains information about the owner + * @return setting owner mac address error + * - 1: no error occured, mac address was set + * - 0: an error occured, owner pointer is NULL */ static uint8_t set_owner_details_mac(owner_details_t* owner){ - // Access the MAC address + if(owner != NULL){ for(int i = 0; i < 6; i++){ - owner->mac_address[i] = netif_default->hwaddr[i]; + owner->mac_address[i] = netif_default->hwaddr[i]; // Access the MAC address } return 1; } else{ - owner_details_error_handler(owner, sod_mac,""); + owner_details_error_handler(owner, SOD_MAC,""); return 0; } @@ -57,11 +65,13 @@ static uint8_t set_owner_details_mac(owner_details_t* owner){ /** * @fn uint8_t set_owner_details_name(owner_details_t*, char*) - * @brief + * @brief set_owner_details_name() sets the owner's name in the owner_details_t struct * - * @param owner - * @param name - * @return + * @param owner owner_details_t structure, it contains information about the owner + * @param name string containing the owner's name + * @return setting owner name error + * - 1: no error occured, name was set + * - 0: an error occured, name pointer is NULL or owner pointer is NULL */ static uint8_t set_owner_details_name(owner_details_t *owner, char *name){ @@ -71,7 +81,7 @@ static uint8_t set_owner_details_name(owner_details_t *owner, char *name){ return 1; } else{ - owner_details_error_handler(owner, sod_name, name); + owner_details_error_handler(owner, SOD_NAME, name); return 0; } @@ -79,11 +89,13 @@ static uint8_t set_owner_details_name(owner_details_t *owner, char *name){ /** * @fn uint8_t set_owner_details_surname(owner_details_t*, char*) - * @brief + * @brief set_owner_details_surname() sets the owner's surname in the owner_details_t struct * - * @param owner - * @param surname - * @return + * @param owner owner_details_t structure, it contains information about the owner + * @param surname string containing the owner's surname + * @return setting owner surname error + * - 1: no error occured, surname was set + * - 0: an error occured, surname pointer is NULL or owner pointer is NULL */ static uint8_t set_owner_details_surname(owner_details_t* owner, char* surname){ if(surname != NULL && owner != NULL){ @@ -92,18 +104,20 @@ static uint8_t set_owner_details_surname(owner_details_t* owner, char* surname){ return 1; } else{ - owner_details_error_handler(owner, sod_surname, surname); + owner_details_error_handler(owner, SOD_SURNAME, surname); return 0; } } /** * @fn uint8_t set_owner_details_reply(owner_details_t, char*) - * @brief + * @brief set_owner_details_reply() sets the UDP reply in the owner_details_t struct * - * @param owner - * @param reply - * @return + * @param owner owner_details_t structure, it contains information about the owner + * @param reply string used to reply to the UDP broadcast + * @return setting owner reply error + * - 1: no error occured, reply was set + * - 0: an error occured, reply pointer is null or owner pointer is NULL */ static uint8_t set_owner_details_reply(owner_details_t *owner, char *reply){ @@ -114,17 +128,19 @@ static uint8_t set_owner_details_reply(owner_details_t *owner, char *reply){ return 1; } else{ - owner_details_error_handler(owner, sod_reply, reply); + owner_details_error_handler(owner, SOD_REPLY, reply); return 0; } } /** * @fn uint8_t format_reply(owner_details_t*) - * @brief + * @brief format_reply() formats all the owner's details into a string * - * @param owner - * @return + * @param owner owner_details_t structure, it contains information about the owner + * @return formatting reply error + * - 1: no error occured, reply was formatted + * - 0: an error occured, owner pointer is NULL */ static uint8_t format_reply(owner_details_t *owner){ @@ -146,19 +162,22 @@ static uint8_t format_reply(owner_details_t *owner){ return 1; } else{ - owner_details_error_handler(owner, f_reply,""); + owner_details_error_handler(owner, F_REPLY,""); return 0; } } /** * @fn uint8_t set_owner_details(owner_details_t*, char*, char*) - * @brief + * @brief set_owner_details() is the interface that can be used in other files + * to set the owner's details * - * @param owner - * @param name - * @param surname - * @return + * @param owner owner_details_t structure, it contains information about the owner + * @param name string containing the new owner's name + * @param surname string containing the new owner's surname + * @return setting owner details error + * - 1: no error occured, details were set + * - 0: an error occured, all or some details weren't set or owner pointer is NULL */ uint8_t set_owner_details(owner_details_t* owner, char* name, char* surname){ if(owner != NULL){ @@ -175,7 +194,7 @@ uint8_t set_owner_details(owner_details_t* owner, char* name, char* surname){ } } else{ - owner_details_error_handler(owner, f_reply,""); + owner_details_error_handler(owner, SOD,""); return 0; } @@ -183,15 +202,16 @@ uint8_t set_owner_details(owner_details_t* owner, char* name, char* surname){ /** * @fn char get_owner_details_name*(owner_details_t) - * @brief + * @brief get_owner_details_name() can be used to get the current owner's name * - * @param owner - * @return + * @param owner owner_details_t structure, it contains information about the owner + * @return name of owner + * this name is set by @see set_owner_details_name() */ char* get_owner_details_name(owner_details_t *owner){ if(owner == NULL || owner->name == NULL){ - owner_details_error_handler(owner, god_name,""); + owner_details_error_handler(owner, GOD_NAME,""); return "|no name yet|"; } return owner->name; @@ -199,15 +219,16 @@ char* get_owner_details_name(owner_details_t *owner){ /** * @fn char get_owner_details_surname*(owner_details_t) - * @brief + * @brief get_owner_details_surname() can be used to get the current owner's surname * - * @param owner - * @return + * @param owner owner_details_t structure, it contains information about the owner + * @return surname of owner + * this name is set by @see set_owner_details_surname() */ char* get_owner_details_surname(owner_details_t* owner){ if(owner == NULL || owner->surname == NULL){ - owner_details_error_handler(owner, god_surname,""); + owner_details_error_handler(owner, GOD_SURNAME,""); return "|no surname yet|"; } return owner->surname; @@ -215,34 +236,35 @@ char* get_owner_details_surname(owner_details_t* owner){ /** * @fn char get_owner_details_reply*(owner_details_t) - * @brief + * @brief get_owner_details_reply() can be used to get the current UDP reply * - * @param - * @return + * @param owner owner_details_t structure, it contains information about the owner + * @return reply for UDP broadcast + * this reply is formatted by @see format_reply() */ char* get_owner_details_reply(owner_details_t *owner){ if(owner == NULL || owner->reply == NULL){ - owner_details_error_handler(owner, god_reply,""); + owner_details_error_handler(owner, GOD_REPLY,""); return "|no reply formatted yet|"; } return owner->reply; } + /** * @fn void udp_receive_callback(void*, struct udp_pcb*, struct pbuf*, const ip_addr_t*, u16_t) - * @brief + * @brief udp_receive_callback() callback function for when a UDP packet has been received. + * it compares the data to a set string @see UDP_QUESTION1, if it's the same it sends the reply string + * @see reply_str back to the client * - * @param arg - * @param upcb - * @param p - * @param addr - * @param port + * @param arg a pointer to some user-defined data or context + * @param connection UDP PCB to be bound with a local address ipaddr and port. + * @param p packet buffern it holds the incoming UDP packet data, including its payload and length + * @param addr ip_addr_t structure that contains the IP address of the sender of the UDP packet + * @param port the source port number of the sender's UDP packet */ -#define MAX_DATA_SIZE 50 // Define the maximum expected data size -#define UDP_QUESTION1 "Where are you?v1.0" - static void udp_receive_callback(void *arg, struct udp_pcb *connection, struct pbuf *p, const ip_addr_t *addr, u16_t port){ int i; int len; @@ -252,8 +274,8 @@ static void udp_receive_callback(void *arg, struct udp_pcb *connection, struct p struct pbuf *p_data; memset(data, 0, sizeof(data)); - // Convert the source IP address to a string for printing. - ipaddr_ntoa_r(addr, source_ip_str, sizeof(source_ip_str)); + + ipaddr_ntoa_r(addr, source_ip_str, sizeof(source_ip_str)); // Convert the source IP address to a string if (p != NULL) { pc = (char*)p->payload; @@ -291,9 +313,13 @@ static void udp_receive_callback(void *arg, struct udp_pcb *connection, struct p /** * @fn err_t init_UDP_server() - * @brief + * @brief init_UDP_server() initialises the UDP connection so that it listens for all traffic on + * port 6400 * - * @return + * @return lwIP error code. + * - ERR_OK. Successful. No error occurred. + * - ERR_USE. The specified ipaddr and port are already bound to by + * another UDP PCB. */ err_t init_UDP_server(){