Merge pull request #1 from csd-robocon-nitk/dev

Add changes for v1,2.0

Author: JoelJojoP

.github/workflows/libraryci.yml

@@ -9,6 +9,6 @@ jobs:
       - uses: actions/checkout@v3
       - uses: arduino/[email protected]
         with:
-          library-manager: submit
+          library-manager: update
           compliance: specification
           project-type: library

LSA08_Simplified.cpp

@@ -1,22 +1,32 @@
 /**
- * Source code of the LSA08_Simplified library
- * Developed by CSD Robocon NITK
- *
- * This is free software. You can redistribute it and/or modify it under
- * the terms of MIT Licence.
- * To view a copy of this license, visit http://opensource.org/licenses/mit-license.php
- *
- * version: 1.0.0
+ * @file LSA08_Simplified.cpp
+ * @author Joel Jojo Painuthara ([email protected])
+ * @brief Source code of the LSA08_Simplified library
+ * @version 1.2.0
+ * @date 2025-05-16
  */
 
 #include "LSA08_Simplified.h"
 
+/**
+ * @brief Construct a new LSA08 object set to analog mode
+ *
+ * @param pin The analog pin to which the LSA08 is connected
+ */
 LSA08::LSA08(unsigned int pin)
 {
     this->mode = LSA08_MODE_ANALOG;
     this->pin = pin;
 }
 
+/**
+ * @brief Construct a new LSA08 object set to hardware serial mode
+ *
+ * @param port The hardware serial port to which the LSA08 is connected
+ * @param baudrate The baud rate for the serial communication
+ * @param addr The address of the LSA08
+ * @param en_pin The pin to which UART enable pin of the LSA08 is connected
+ */
 LSA08::LSA08(HardwareSerial *port, int baudrate, unsigned int addr, unsigned int en_pin)
 {
     this->mode = LSA08_MODE_SERIAL;
@@ -26,6 +36,14 @@ LSA08::LSA08(HardwareSerial *port, int baudrate, unsigned int addr, unsigned int
     this->baudrate = baudrate;
 }
 
+/**
+ * @brief Construct a new LSA08 object set to software serial mode
+ *
+ * @param port The software serial port to which the LSA08 is connected
+ * @param baudrate The baud rate for the serial communication
+ * @param addr The address of the LSA08
+ * @param en_pin The pin to which the UART enable pin of the LSA08 is connected
+ */
 LSA08::LSA08(SoftwareSerial *port, int baudrate, unsigned int addr, unsigned int en_pin)
 {
     this->mode = LSA08_MODE_SOFT_SERIAL;
@@ -34,16 +52,37 @@ LSA08::LSA08(SoftwareSerial *port, int baudrate, unsigned int addr, unsigned int
     this->pin = en_pin;
 }
 
+/**
+ * @brief Initialize the LSA08 sensor
+ *
+ * This function sets the pin mode and initializes the serial communication.
+ * It should be called in the setup() function of the Arduino sketch when using
+ * the LSA08 in serial mode (both hardware and software serial).
+ */
 void LSA08::init()
 {
-    pinMode(this->pin, OUTPUT);
-    digitalWrite(this->pin, HIGH);
-    if(this->mode == LSA08_MODE_SERIAL)
-        this->port->begin(baudrate);
+    if (this->mode == LSA08_MODE_SERIAL)
+    {
+        pinMode(this->pin, OUTPUT);
+        digitalWrite(this->pin, HIGH);
+        this->port->begin(this->baudrate);
+    }
     else if (this->mode == LSA08_MODE_SOFT_SERIAL)
-	    this->soft_port->begin(9600);
+    {
+        pinMode(this->pin, OUTPUT);
+        digitalWrite(this->pin, HIGH);
+        this->soft_port->begin(this->baudrate);
+    }
 }
 
+/**
+ * @brief Disable line sensor reading from the LSA08
+ * 
+ * This function sets the UART enable pin to HIGH, disabling the stream of line sensor reading from the LSA08.
+ * To be used only when the LSA08 is set to serial mode (both hardware and software serial).
+ * 
+ * @return @ref MODE_ERROR if the LSA08 is not set to serial mode, otherwise @ref SYS_OK
+ */
 int LSA08::disable_stream()
 {
     if (mode != LSA08_MODE_SERIAL && mode != LSA08_MODE_SOFT_SERIAL)
@@ -54,6 +93,14 @@ int LSA08::disable_stream()
     return SYS_OK;
 }
 
+/**
+ * @brief Enable line sensor reading from the LSA08
+ * 
+ * This function sets the UART enable pin to LOW, enabling the stream of line sensor reading from the LSA08.
+ * To be used only when the LSA08 is set to serial mode (both hardware and software serial).
+ * 
+ * @return @ref MODE_ERROR if the LSA08 is not set to serial mode, otherwise @ref SYS_OK
+ */
 int LSA08::enable_stream()
 {
     if (mode != LSA08_MODE_SERIAL && mode != LSA08_MODE_SOFT_SERIAL)
@@ -64,6 +111,16 @@ int LSA08::enable_stream()
     return SYS_OK;
 }
 
+/**
+ * @brief Set the UART mode of the LSA08
+ * 
+ * This function sets the UART mode of the LSA08 to either none, digital, analog, or raw.
+ * To be used only when the LSA08 is set to serial mode (both hardware and software serial).
+ * 
+ * @param mode The UART mode to set (refer to @ref uart_mode for valid modes)
+ * @return @ref MODE_ERROR if the LSA08 is not set to serial mode, @ref BAD_PACKET if the
+ * UART mode is invalid, otherwise @ref SYS_OK
+ */
 int LSA08::set_uart_mode(uart_mode mode)
 {
     if (this->mode != LSA08_MODE_SERIAL && this->mode != LSA08_MODE_SOFT_SERIAL)
@@ -77,6 +134,15 @@ int LSA08::set_uart_mode(uart_mode mode)
     return send_packet('D', (unsigned char)mode, COM_TYPE_COMMAND);
 }
 
+/**
+ * @brief Calibrate the LSA08 sensor
+ * 
+ * This function sends a command to the LSA08 to calibrate the sensor.
+ * To be used only when the LSA08 is set to serial mode (both hardware and software serial).
+ * 
+ * @return @ref MODE_ERROR if the LSA08 is not set to serial mode, @ref BAD_PACKET
+ * if request failed, otherwise @ref SYS_OK
+ */
 int LSA08::calibrate()
 {
     if (mode != LSA08_MODE_SERIAL && mode != LSA08_MODE_SOFT_SERIAL)
@@ -86,6 +152,16 @@ int LSA08::calibrate()
     return send_packet('C', 0, COM_TYPE_COMMAND);
 }
 
+/**
+ * @brief Set the line mode of the LSA08 sensor
+ * 
+ * This function sets the line mode of the LSA08 sensor to either light or dark.
+ * To be used only when the LSA08 is set to serial mode (both hardware and software serial).
+ * 
+ * @param mode The line mode to set (refer to @ref line_mode for valid modes)
+ * @return @ref MODE_ERROR if the LSA08 is not set to serial mode, @ref BAD_PACKET if the
+ * line mode is invalid, otherwise @ref SYS_OK
+ */
 int LSA08::set_line_mode(line_mode mode)
 {
     if (this->mode != LSA08_MODE_SERIAL && this->mode != LSA08_MODE_SOFT_SERIAL)
@@ -99,6 +175,17 @@ int LSA08::set_line_mode(line_mode mode)
     return send_packet('L', (unsigned char)mode, COM_TYPE_COMMAND);
 }
 
+/**
+ * @brief Set the threshold for the LSA08 sensor
+ * 
+ * This function sets the threshold for the LSA08 sensor to detect lines.
+ * The threshold value should be between 0 and 7.
+ * To be used only when the LSA08 is set to serial mode (both hardware and software serial).
+ * 
+ * @param threshold The threshold value to set
+ * @return @ref MODE_ERROR if the LSA08 is not set to serial mode, @ref BAD_PACKET if the
+ * threshold value is invalid, otherwise @ref SYS_OK
+ */
 int LSA08::set_threshold(unsigned int threshold)
 {
     if (this->mode != LSA08_MODE_SERIAL && this->mode != LSA08_MODE_SOFT_SERIAL)
@@ -112,6 +199,16 @@ int LSA08::set_threshold(unsigned int threshold)
     return send_packet('T', (unsigned char)threshold, COM_TYPE_COMMAND);
 }
 
+/**
+ * @brief Read the line sensor data from the LSA08
+ * 
+ * This function reads the line sensor data from the LSA08.
+ * The data is read from the analog pin if the LSA08 is set to analog mode,
+ * or from the serial port if it is set to serial mode (both hardware and
+ * software serial).
+ * 
+ * @return The line sensor data
+ */
 unsigned int LSA08::read_line()
 {
     if (this->mode == LSA08_MODE_SERIAL || this->mode == LSA08_MODE_SOFT_SERIAL)
@@ -126,25 +223,46 @@ unsigned int LSA08::read_line()
         return 0;
 }
 
-unsigned char LSA08::send_packet(unsigned char command, unsigned char value, com_type type)
+/**
+ * @brief Send a packet to the LSA08 sensor
+ * 
+ * This function sends a request and value (is applicable) to the LSA08 sensor.
+ * The request and value are sent over the serial port if the LSA08 is set
+ * to serial mode (both hardware and software serial).
+ * 
+ * @param request The request to send (refer to the LSA08 documentation for valid requests)
+ * @param value The value to send with the request (if applicable)
+ * @param type The type of request - command or data
+ * @return The response from the LSA08 sensor
+ */
+unsigned char LSA08::send_packet(unsigned char request, unsigned char value, com_type type)
 {
     if (mode == LSA08_MODE_SERIAL)
     {
         port->write(addr);
-        port->write(command);
+        port->write(request);
         port->write(value);
-        port->write(addr + command + value);
+        port->write(addr + request + value);
     }
     else if (mode == LSA08_MODE_SOFT_SERIAL)
     {
         soft_port->write(addr);
-        soft_port->write(command);
+        soft_port->write(request);
         soft_port->write(value);
-        soft_port->write(addr + command + value);
+        soft_port->write(addr + request + value);
     }
     return get_response(type);
 }
 
+/**
+ * @brief Get the data from the LSA08 sensor
+ * 
+ * This function reads the data from the LSA08 sensor.
+ * The data is read from the serial port if the LSA08 is set to serial mode
+ * (both hardware and software serial).
+ * 
+ * @return The data read from the LSA08 sensor
+ */
 unsigned char LSA08::get_data()
 {
     unsigned char data = 0;
@@ -165,6 +283,16 @@ unsigned char LSA08::get_data()
     return data;
 }
 
+/**
+ * @brief Get the response from the LSA08 sensor
+ * 
+ * This function reads the response from the LSA08 sensor.
+ * The response is read from the serial port if the LSA08 is set to serial mode
+ * (both hardware and software serial).
+ * 
+ * @param type The type of request for which response is awaited (command or data)
+ * @return The response from the LSA08 sensor
+ */
 unsigned char LSA08::get_response(com_type type)
 {
     unsigned char data[2] = {0, 0};

LSA08_Simplified.h

@@ -1,49 +1,95 @@
 /**
- * Header for LSA08_Simplified library
- * Developed by CSD Robocon NITK
- *
- * This is free software. You can redistribute it and/or modify it under
- * the terms of MIT Licence.
- * To view a copy of this license, visit http://opensource.org/licenses/mit-license.php
- *
- * version: 1.0.0
+ * @file LSA08_Simplified.h
+ * @author Joel Jojo Painuthara ([email protected])
+ * @brief Header file of the LSA08_Simplified library
+ * @version 1.2.0
+ * @date 2025-05-16
  */
 
 #include <Arduino.h>
 #include <SoftwareSerial.h>
 
+/**
+ * @brief Error code when using LSA08 in the wrong mode
+ * 
+ */
 #define MODE_ERROR -1
+/**
+ * @brief Error code when data being sent to LSA08 is invalid or connection
+ * is not established
+ * 
+ */
 #define BAD_PACKET 1
+/**
+ * @brief Code when no error occurs
+ * 
+ */
 #define SYS_OK 0
 
+/**
+ * @brief Mode of communication with the LSA08 sensor
+ * 
+ */
 typedef enum
 {
-    LSA08_MODE_ANALOG,
-    LSA08_MODE_DIGITAL,
+    /** Analog mode via analog pin */
+    LSA08_MODE_ANALOG, 
+    /** Digital mode via 8 digital pins */
+    LSA08_MODE_DIGITAL, 
+    /** Hardware serial mode via UART pins*/
     LSA08_MODE_SERIAL,
+    /** Software serial mode */
     LSA08_MODE_SOFT_SERIAL
 } lsa08_mode;
 
+/**
+ * @brief UART mode of the LSA08 sensor
+ * 
+ */
 typedef enum
 {
+    /** No UART mode (No data output)*/
     UART_MODE_NONE,
+    /** Digital UART mode (1 byte digital value from sensor)*/
     UART_MODE_DIGITAL,
+    /** Analog UART mode (1 byte line position value. Value between 0-70 of
+     * line is detected, 255 otherwise)*/
     UART_MODE_ANALOG,
+    /** Raw UART mode (9 bytes of raw analog value from sensor)*/
     UART_MODE_RAW
 } uart_mode;
 
+/**
+ * @brief Line mode of the LSA08 sensor
+ * 
+ */
 typedef enum
 {
+    /** Detect dark line */
     DARK_LINE,
+    /** Detect light line */
     LIGHT_LINE
 } line_mode;
 
+/**
+ * @brief Type of request sent to LSA08 sensor
+ * 
+ */
 typedef enum
 {
+    /** Command request (Response is OK if command is valid) */
     COM_TYPE_COMMAND,
+    /** Data request (Response is the data from the sensor) */
     COM_TYPE_DATA
 } com_type;
 
+/**
+ * @brief Definition of LSA08 object
+ * 
+ * This class provides methods to initialize, configure, and read data from
+ * the LSA08 line sensor. It currently supports analog, hardware and software serial
+ * communication modes.
+ */
 class LSA08
 {
 private:

README.md

@@ -1,6 +1,6 @@
 # LSA08_Simplified
 
-![v1.1.0](https://img.shields.io/badge/Version-1.0.0-blue)
+![v1.2.0](https://img.shields.io/badge/Version-1.2.0-blue)
 ![Library CI](https://github.com/csd-robocon-nitk/LSA08_Simplified/actions/workflows/libraryci.yml/badge.svg)
 
 An easy to use Arduino library for interfacing LSA08 line sensor.