Merge pull request #217 from RocioRojas/doc_serialization

doc: make documentation firmware

examples/moisture_sensor_hw390/doc.txt

@@ -7,7 +7,7 @@
  */
 
 /**
- * @defgroup    moisture_sensor  Analog capacitive moisture sensor
+ * @defgroup    moisture_sensor_example  Analog capacitive moisture sensor
  * @ingroup     examples
  * @brief       Example dedicated to use the analog soil moisture sensor
  * @author      xkevin190 <[email protected]>

firmware/doc.txt

@@ -1,8 +1,18 @@
 /**
 @defgroup m4a-firmware  Reference firmware
 
-# What goes here?
+### What goes here?
 Specific documentation for our reference firmware ; m4a-firmware
 
-Add more: specific documentation for the m4a-firmware
+You can find specific documentation for the sys, peripherals, and network folders.
+
+
+### network
+UDP client, UDP server.
+
+### peripherals
+Humidity and temperature sensors.
+
+### sys
+AT commands, udp serialization, storage, ipv6 address.
 */

firmware/main.c

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021 Mesh4all <mesh4all.org>
+ * Copyright (c) 2022 Mesh4all <mesh4all.org>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,7 +17,6 @@
 /**
  * @brief       Main firmware file
  *
- * @copyright   Copyright (c) 2021 Mesh for all
  * @author      luisan00 <[email protected]>
  *
  */
@@ -32,7 +31,6 @@
 #include "log.h"
 #include "board.h"
 
-
 static shell_command_t shell_extended_commands[] = {
     {NULL, NULL, NULL}};
 

firmware/network/doc.txt

@@ -0,0 +1,17 @@
+/**
+@defgroup network Network module
+@ingroup  m4a-firmware
+
+### What goes here?
+Specific documentation for our reference network;
+In the next module you can find:
+
+### udp_client
+
+In this module is used to send the sensors values.
+
+### udp_server
+
+In this module is used to get the sensor values.
+
+*/

firmware/network/udp_client/doc.txt

@@ -0,0 +1,10 @@
+/**
+@defgroup udp_client Udp Client
+@ingroup  network
+
+### What goes here?
+
+This module is used to set an udp client. The function ``` udp_send ``` is used to send the sensors values specifying port,
+address to which the message will be sent, the message (parameter) and the size of the message.
+
+*/

firmware/network/udp_client/include/udp_client.h

@@ -15,8 +15,9 @@
  */
 
 /**
+ * @ingroup     udp_client
  * @{
- * @file        udp_m4a.h
+ * @file
  * @brief       udp client lib used to send the sensor values
  * @author      xkevin190 <[email protected]>
  *
@@ -30,7 +31,7 @@ extern "C" {
 #endif
 
 /**
- * @brief this function is used for send the sensors values
+ * @brief this function is used to send the sensors values
  *
  * @param port  [in]            port to which the message will be sent
  * @param address [int]         address to which the message will be sent
@@ -44,3 +45,4 @@ int udp_send(int *port, char *address, uint8_t *message, size_t *payload_len);
 }
 #endif
 #endif /* UDP_CLIENT_H */
+/** @} */

firmware/network/udp_server/doc.txt

@@ -0,0 +1,10 @@
+/**
+@defgroup udp_server Udp server
+@ingroup  network
+
+### What goes here?
+
+This module is used to set an udp server. The function ``` udp_server ``` is used to init the server,
+containing the callback function to handle requests.
+
+*/

firmware/network/udp_server/include/udp_server.h

@@ -15,9 +15,10 @@
  */
 
 /**
+ * @ingroup     udp_server
  * @{
- * @file        udp_m4a.h
- * @brief       udp libs
+ * @file
+ * @brief       udp server lib used to get the sensor values
  * @author      xkevin190 <[email protected]>
  *
  */
@@ -30,27 +31,31 @@ extern "C" {
 #endif
 
 /**
- * @brief this is a struct  used for init udp server
+ * @brief this is a struct used to init udp server
  */
 typedef struct {
-    char *port;                              /*!< port where will listen udp server */
+    char *port;                                     /*!< port where will listen udp server */
     void (*callback)(uint8_t *message, size_t len); /*!< this is a callback this function will
-                                                  be executed when arrive new values
-                                             */
+                                                    be executed when arrive new values */
 } udpf_payload;
 
 /**
  * @brief  udp server function this function is used for init udp server
  *
- * @param argv [in] this param will content  the callback and port where will listen el server
+ * @param argv [in] this param will content the callback and port where will listen the server
  * @return  0 Satisfactory result
  *         -1 Failed result
  */
 int udp_server(udpf_payload *argv);
 
+/**
+ * @brief This function function is used to set the callback function to the udp server thread
+ * @param args [in] UDP payload pointer
+ */
 void *_udp_serverf(void *args);
 
 #ifdef __cplusplus
 }
 #endif
 #endif /* UDP_SERVER_H */
+/** @} */

firmware/peripherals/doc.txt

@@ -0,0 +1,17 @@
+/**
+@defgroup peripherals Peripherals
+@ingroup  m4a-firmware
+
+### What goes here?
+Specific documentation for our reference peripherals;
+In the next module you can find:
+
+### ds18_sensor
+
+Module to get temperature data.
+
+### moisture_sensor
+
+Module to get moisture data.
+
+*/

firmware/peripherals/ds18_sensor/doc.txt

@@ -0,0 +1,11 @@
+/**
+@defgroup ds18_sensor Ds18 sensor
+@ingroup  peripherals
+
+### What goes here?
+
+This module is used to get the data of the temperature sensor. The function
+``` init_temperature_sensor ```initialize the sensor and the function
+``` get_temperature_value ``` gets the values.
+
+*/

firmware/peripherals/ds18_sensor/ds18_sensor.c

@@ -1,4 +1,23 @@
-
+/*
+ * Copyright (c) 2022 Mesh4all <mesh4all.org>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * @brief  Moisture sensor
+ *
+ * @author  xkevin190 <[email protected]>
+ */
 #include <stdio.h>
 #include <stdlib.h>
 #include "ds18.h"

firmware/peripherals/ds18_sensor/include/ds18_sensor.h

@@ -13,14 +13,12 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
 /**
- * @ingroup     m4a-firmware
+ * @ingroup     ds18_sensor
  * @{
  * @file
- * @brief       moisture sensor file
+ * @brief       temperature sensor module
  *
- * @copyright   Copyright (c) 2021 Mesh for all
  * @author      xkevin190 <[email protected]>
  *
  */
@@ -44,7 +42,7 @@ int init_temperature_sensor(int pin);
  * @brief  Function to get the sensor data
  * @param[out]  output This variable will return the temperature value
  * @return  0 Satisfactory result
- *         -1 Sailed result
+ *         -1 Failed result
  */
 int get_temperature_value(int16_t* output);
 

firmware/peripherals/moisture_sensor/doc.txt

@@ -0,0 +1,12 @@
+/**
+@defgroup moisture_sensor Moisture sensor
+@ingroup  peripherals
+
+### What goes here?
+
+This module gets the data of the moisture sensor.
+
+Note:  This is an adc device, for the correct functioning of this module you have to use 3.3V
+and 10bits resolution.
+
+*/

firmware/peripherals/moisture_sensor/include/moisture_sensor.h

@@ -15,12 +15,13 @@
  */
 
 /**
- * @ingroup     m4a-firmware
+ * @ingroup     moisture_sensor
  * @{
  * @file
- * @brief       moisture sensor file
+ * @brief       This is a module created for hw390 moisture sensor. This is an adc device,
+ *              for the correct functioning of this module you have
+ *              to use 3.3V and 10bits resolution.
  *
- * @copyright   Copyright (c) 2021 Mesh for all
  * @author      xkevin190 <[email protected]>
  *
  */
@@ -31,20 +32,15 @@
 extern "C"
 {
 #endif
-/**
- * this a module created for hw390 moisture sensor this is an adc device,
- * for the correct func oof this module you will be use 3.3v and one resolution of 10bits
- *
- */
 
 /**
- * @brief  this function initializes the moisture sensor
+ * @brief  This function initializes the moisture sensor
  * @return  0 satisfactory result
  *         -1 failed result
  */
 int init_moisture(void);
 /**
- * @brief  function to get the sensor data
+ * @brief  Function to get the sensor data
  * @param[out]  output this variable will return the moisture value
  * @return  0 satisfactory result
  *         -1 failed result

firmware/peripherals/moisture_sensor/moisture_sensor.c

@@ -1,4 +1,23 @@
-
+/*
+ * Copyright (c) 2022 Mesh4all <mesh4all.org>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * @brief  Moisture sensor
+ *
+ * @author  xkevin190 <[email protected]>
+ */
 #include <stdio.h>
 #include <stdlib.h>
 #include "periph/adc.h"
@@ -37,7 +56,7 @@ int get_moisture_value(int* output)
         double finished = ((sample - min) * 100 / cal);
         int moisture = 100 - finished;
 
-        if(moisture <= 100 && moisture >= 0 ){
+        if (moisture <= 100 && moisture >= 0 ){
             // printf("the moisture  sensor is percent %i \n",  moisture);
             *output = moisture;
         } else if (moisture < 0) {

firmware/sys/at_client/doc.txt

@@ -1,8 +1,8 @@
 /**
-@defgroup at_client
+@defgroup at_client  At client
 @ingroup     sys
 
-# What goes here?
+### What goes here?
 
 You have at command handler, which can be send with the shell, the following list has the command options: