Implement SUP (Simple UART Protocol)

Author: m3y54m

.clang-format

@@ -1,11 +1,8 @@
-# This .clang-format file is tailored for C projects following widely accepted best practices.
-# It enforces readability, consistency, and compatibility with most open source C codebases.
 BasedOnStyle: LLVM
-Language: C
 IndentWidth: 4
 TabWidth: 4
 UseTab: Never
-ColumnLimit: 80
+ColumnLimit: 120
 AllowShortIfStatementsOnASingleLine: false
 AllowShortLoopsOnASingleLine: false
 AllowShortFunctionsOnASingleLine: InlineOnly

CMakeLists.txt

@@ -1,8 +1,11 @@
-cmake_minimum_required(VERSION 3.10)
+cmake_minimum_required(VERSION 3.13)
 
 # Use the AVR toolchain file (set before project())
 set(CMAKE_TOOLCHAIN_FILE ${CMAKE_CURRENT_SOURCE_DIR}/toolchain.cmake CACHE STRING "AVR toolchain file")
-project("AVR Bootloader" C)
+
+# Dynamically set project name from directory name
+get_filename_component(PROJECT_NAME ${CMAKE_CURRENT_SOURCE_DIR} NAME)
+project(${PROJECT_NAME} C)
 
 # ---------------------------------------------------------------------------
 # Common configuration
@@ -14,6 +17,9 @@ set(MCU atmega328p)
 # This definition is essential for libraries like <util/delay.h>
 set(F_CPU 16000000UL)
 
+# UART Baud rate settings
+set(BAUD 9600)
+
 # Programmer for avrdude
 set(AVRDUDE_PROGRAMMER usbasp)
 
@@ -23,11 +29,12 @@ set(CMAKE_C_STANDARD_REQUIRED ON)
 set(CMAKE_C_EXTENSIONS OFF)
 
 # Common compiler flags for AVR targets
-set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wall -Os -mmcu=${MCU} -DF_CPU=${F_CPU}")
+set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wall -Os -mmcu=${MCU} -DF_CPU=${F_CPU} -DBAUD=${BAUD}")
 
 # Add subprojects
 add_subdirectory(blinky)
 add_subdirectory(bootloader_hardcoded)
+add_subdirectory(simple_uart_protocol)
 
 # Clean all build files and directories
 add_custom_target(

README.md

@@ -5,16 +5,19 @@ To prepare your build environment first read this tutorial:
 - [Getting started with AVR programming](https://github.com/m3y54m/start-avr)
 
 > [!NOTE]
-> **A "bootloader" is a small program that is written to a dedicated section of the non-volatile memory of a computer.
+> A "bootloader" is a small program that is written to a dedicated section of the non-volatile memory of a computer.
 > In microcontrollers it is mostly used to facilitate the updating of the main program by utilizing a communication peripheral,
 > thereby eliminating the requirement for an external programmer. In more sophisticated computer systems, a bootloader is mostly
-> employed to pre-configure the system clock and input/output interfaces.**
+> employed to pre-configure the system clock and input/output interfaces.
 >
-> **With this definition in mind, what follows is not a practical bootloader. Instead, it is a tutorial designed to step-by-step
+> With this definition in mind, what follows is not a practical bootloader. Instead, it is a tutorial designed to step-by-step
 > illustrate the process of program compilation and configuration to show how a bootloader can self-program the microcontroller.
-> This bootloader is literally hardcoding the binary data of the program you want to upload (**[**`blinky`**](blinky)**) in the
+> This bootloader is literally hardcoding the binary data of the program you want to upload ([`blinky`](blinky)) in the
 > bootloader itself. With some small changes in code you can modify it to receive binary of the program you want to upload through
-> UART, I2C or SPI. To learn how to write a more sophisticated and secure bootloader study the** [**resources**](#resources).
+> UART, I2C or SPI. To learn how to write a more sophisticated and secure bootloader study the [resources](#resources).
+
+> [!CAUTION]
+> Please note that the code and materials provided in this repository are intended for **EDUCATIONAL** purposes only and is **NOT SAFE** to be used in production.
 
 *DONE:*
 - Configure fuse bits settings for bootloader section size and reset vector

blinky/CMakeLists.txt

@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 3.10)
+cmake_minimum_required(VERSION 3.13)
 
 # Dynamically set project name from directory name
 get_filename_component(PROJECT_NAME ${CMAKE_CURRENT_SOURCE_DIR} NAME)

blinky/src/main.c

@@ -1,11 +1,16 @@
 /**
- * @brief Blinky application for the ATmega328P.
+ * @file main.c
+ * @brief Blinky application
+ *
  * @details This application blinks an LED connected to pin PB5
  * (Arduino Uno D13) at a 5Hz frequency.
+ *
+ * @warning This code is provided for educational purposes only and is not
+ * intended for production use. Use at your own risk. No warranty is provided.
  */
 
-#include <stdint.h>
 #include <avr/io.h>
+#include <stdint.h>
 #include <util/delay.h>
 
 #define LED_PIN PB5
@@ -19,6 +24,7 @@ int main(void)
     {
         // Toggle the LED
         PORTB ^= (1U << LED_PIN);
+
         // Wait for 100 ms
         _delay_ms(100U);
     }

bootloader_hardcoded/CMakeLists.txt

@@ -1,5 +1,5 @@
 
-cmake_minimum_required(VERSION 3.10)
+cmake_minimum_required(VERSION 3.13)
 
 # Dynamically set project name from directory name
 get_filename_component(PROJECT_NAME ${CMAKE_CURRENT_SOURCE_DIR} NAME)

bootloader_hardcoded/src/main.c

@@ -1,9 +1,14 @@
 /**
- * @brief A hardcoded bootloader for the ATmega328P.
+ * @file main.c
+ * @brief Hardcoded bootloader
+ *
  * @details This bootloader checks if a user application exists at
- * destination_address 0x0000. If not, it flashes a built-in "blinky"
+ * destination_address 0x0000. If not, it flashes a hardcoded "blinky"
  * application to that destination_address. It then jumps to the application
  * code.
+ *
+ * @warning This code is provided for educational purposes only and is not
+ * intended for production use. Use at your own risk. No warranty is provided.
  */
 
 #include <avr/boot.h>
@@ -25,20 +30,15 @@
  * Program size: 162 bytes.
  */
 static const uint8_t hardcoded_blinky_bin[] PROGMEM = {
-    0x0C, 0x94, 0x34, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00,
-    0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00,
-    0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00,
-    0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00,
-    0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00,
-    0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00,
-    0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00,
-    0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00,
-    0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x11, 0x24, 0x1F, 0xBE,
-    0xCF, 0xEF, 0xD8, 0xE0, 0xDE, 0xBF, 0xCD, 0xBF, 0x0E, 0x94, 0x40, 0x00,
-    0x0C, 0x94, 0x4F, 0x00, 0x0C, 0x94, 0x00, 0x00, 0x25, 0x9A, 0x90, 0xE2,
-    0x85, 0xB1, 0x89, 0x27, 0x85, 0xB9, 0x2F, 0xEF, 0x31, 0xEE, 0x84, 0xE0,
-    0x21, 0x50, 0x30, 0x40, 0x80, 0x40, 0xE1, 0xF7, 0x00, 0xC0, 0x00, 0x00,
-    0xF3, 0xCF, 0xF8, 0x94, 0xFF, 0xCF};
+    0x0C, 0x94, 0x34, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94,
+    0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00,
+    0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94,
+    0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00,
+    0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94,
+    0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x0C, 0x94, 0x3E, 0x00, 0x11, 0x24, 0x1F, 0xBE,
+    0xCF, 0xEF, 0xD8, 0xE0, 0xDE, 0xBF, 0xCD, 0xBF, 0x0E, 0x94, 0x40, 0x00, 0x0C, 0x94, 0x4F, 0x00, 0x0C, 0x94,
+    0x00, 0x00, 0x25, 0x9A, 0x90, 0xE2, 0x85, 0xB1, 0x89, 0x27, 0x85, 0xB9, 0x2F, 0xEF, 0x31, 0xEE, 0x84, 0xE0,
+    0x21, 0x50, 0x30, 0x40, 0x80, 0x40, 0xE1, 0xF7, 0x00, 0xC0, 0x00, 0x00, 0xF3, 0xCF, 0xF8, 0x94, 0xFF, 0xCF};
 
 // --- Configuration Constants ---
 
@@ -119,9 +119,8 @@ static bool user_app_exists(void)
  * @note This function must be called from the bootloader section.
  * @return true on success, false on error
  */
-static bool write_to_flash(const uint32_t destination_address,
-                           const uint8_t* source_data,
-                           const size_t   source_data_size)
+static bool write_to_flash(const uint32_t destination_address, const uint8_t* source_data,
+                           const size_t source_data_size)
 {
     if ((source_data == NULL) || (source_data_size == 0))
     {
@@ -146,8 +145,7 @@ static bool write_to_flash(const uint32_t destination_address,
     eeprom_busy_wait();
 
     // Process each page
-    for (uint32_t page_addr = destination_address;
-         page_addr < (destination_address + source_data_size);
+    for (uint32_t page_addr = destination_address; page_addr < (destination_address + source_data_size);
          page_addr += SPM_PAGESIZE)
     {
         // Erase page
@@ -156,8 +154,7 @@ static bool write_to_flash(const uint32_t destination_address,
         boot_spm_busy_wait();
 
         // Fill page buffer word by word
-        for (uint16_t offset = 0; offset < SPM_PAGESIZE;
-             offset += WORD_SIZE_BYTES)
+        for (uint16_t offset = 0; offset < SPM_PAGESIZE; offset += WORD_SIZE_BYTES)
         {
             uint16_t word_data = FLASH_EMPTY_WORD; // Default to erased state
 
@@ -226,9 +223,9 @@ static void __attribute__((noreturn)) jump_to_user_app(void)
 
     // Jump to application start address
     // The user application expects r1 to be zero when it starts
-    __asm__ __volatile__("clr r1\n\t" // Clear register r1 (zero register)
-                         "jmp %0"     // Jump to application
-                         :            // Output operands (empty)
+    __asm__ __volatile__("clr r1\n\t"                 // Clear register r1 (zero register)
+                         "jmp %0"                     // Jump to application
+                         :                            // Output operands (empty)
                          : "i"(USER_APP_START_ADDR)); // Input operands
 
     // Should never reach here

simple_uart_protocol/CMakeLists.txt

@@ -0,0 +1,23 @@
+cmake_minimum_required(VERSION 3.13)
+
+# Dynamically set project name from directory name
+get_filename_component(PROJECT_NAME ${CMAKE_CURRENT_SOURCE_DIR} NAME)
+project(${PROJECT_NAME} C)
+
+add_executable(${PROJECT_NAME}.elf src/main.c src/sup.c)
+
+add_custom_target(
+  ${PROJECT_NAME}_build ALL
+  COMMAND avr-objcopy -j .text -j .data -O ihex ${PROJECT_NAME}.elf ${PROJECT_NAME}.hex
+  COMMAND avr-objcopy -j .text -j .data -O binary ${PROJECT_NAME}.elf ${PROJECT_NAME}.bin
+  COMMAND avr-size --format=avr --mcu=${MCU} ${PROJECT_NAME}.elf
+  DEPENDS ${PROJECT_NAME}.elf
+  COMMENT "[[${PROJECT_NAME}]] Building .hex and .bin files for \"${MCU}\""
+)
+
+add_custom_target(
+  ${PROJECT_NAME}_flash
+  COMMAND avrdude -c ${AVRDUDE_PROGRAMMER} -p ${MCU} -U flash:w:${PROJECT_NAME}.hex
+  DEPENDS ${PROJECT_NAME}_build
+  COMMENT "[[${PROJECT_NAME}]] Flashing to \"${MCU}\" using \"${AVRDUDE_PROGRAMMER}\""
+)

simple_uart_protocol/demo.py

@@ -0,0 +1,148 @@
+import serial
+import time
+
+# SUP Protocol Constants
+SUP_SOF = 0xA1
+SUP_EOF = 0xE9
+SUP_MAX_PAYLOAD_SIZE = 64
+
+# SUP Frame IDs
+SUP_ID_ACK = 0x01  # Acknowledgment for received frame
+SUP_ID_NACK = 0x02  # Negative Acknowledgment for received frame
+SUP_ID_DATA = 0x03  # Binary data chunk transfer
+SUP_ID_CMD_FW_UPDATE = 0x11  # Firmware Update Command
+
+
+# SUP Protocol Functions
+def calculate_checksum(payload_size, id, payload):
+    """Calculates the checksum for a SUP frame."""
+    checksum = payload_size + id
+    for byte in payload:
+        checksum += byte
+    return checksum & 0xFF  # Ensure checksum is a single byte
+
+
+def create_sup_frame(id, payload=b""):
+    """Creates a complete SUP frame as a bytearray."""
+    payload_size = len(payload)
+    if payload_size > SUP_MAX_PAYLOAD_SIZE:
+        raise ValueError(
+            f"Payload size ({payload_size}) exceeds max limit ({SUP_MAX_PAYLOAD_SIZE})"
+        )
+
+    checksum = calculate_checksum(payload_size, id, payload)
+
+    frame = bytearray()
+    frame.append(SUP_SOF)
+    frame.append(id)
+    frame.append(payload_size)
+    frame.extend(payload)
+    frame.append(checksum)
+    frame.append(SUP_EOF)
+
+    return frame
+
+
+def parse_sup_frames(buffer: bytearray):
+    """Parse a byte buffer and return a list of full SUP frames (each as bytearray).
+
+    A SUP frame has the structure:
+      SOF(1) ID(1) SIZE(1) PAYLOAD(SIZE) CHECKSUM(1) EOF(1)
+
+    This function extracts complete frames and skips incomplete or corrupted segments.
+    """
+    frames = []
+    i = 0
+    buf_len = len(buffer)
+    while i < buf_len:
+        # find next SOF
+        if buffer[i] != SUP_SOF:
+            i += 1
+            continue
+
+        # need at least SOF + ID + SIZE + CHECKSUM + EOF => 5 bytes (with 0 payload)
+        if i + 5 > buf_len:
+            # incomplete header/short tail -- wait for more bytes
+            break
+
+        # read size
+        payload_size = buffer[i + 2]
+        total_len = payload_size + 5  # SOF, ID, SIZE, PAYLOAD, CHK, EOF => payload+5
+
+        # check if full frame is present
+        if i + total_len > buf_len:
+            # incomplete frame
+            break
+
+        # check EOF marker
+        if buffer[i + total_len - 1] != SUP_EOF:
+            # malformed frame: skip this SOF and continue searching
+            i += 1
+            continue
+
+        # extract full frame
+        frame = bytearray(buffer[i : i + total_len])
+        frames.append(frame)
+
+        # advance index past this frame
+        i += total_len
+
+    return frames
+
+
+def main():
+    """Main function to demonstrate communication with the AVR."""
+    # Configure the serial port
+    ser = serial.Serial(
+        port="COM9",  # Change to your COM port (e.g., '/dev/ttyACM0' on Linux)
+        baudrate=9600,
+        parity=serial.PARITY_NONE,
+        stopbits=serial.STOPBITS_ONE,
+        bytesize=serial.EIGHTBITS,
+        timeout=1,
+    )
+
+    print(f"Connected to {ser.name}")
+
+    try:
+        # Example 1: Send a simple message to the AVR
+        demo_id = SUP_ID_DATA
+        demo_payload = bytearray([0x44, 0x55, 0x66, 0x77])
+
+        tx_frame = create_sup_frame(demo_id, demo_payload)
+        print(f"Sending frame:\r\n  {[f'{b:02X}' for b in tx_frame]}")
+        ser.write(tx_frame)
+
+        # Wait for a response from the AVR
+        time.sleep(0.5)
+
+        rx_buffer = bytearray()
+        while ser.in_waiting > 0:
+            rx_buffer.extend(ser.read(ser.in_waiting))
+            time.sleep(0.1)  # Give some time for more data to arrive
+
+        if rx_buffer:
+            # split into SUP frames (there may be multiple concatenated frames)
+            parsed = parse_sup_frames(rx_buffer)
+            if parsed:
+                print("Received frames:")
+                for f in parsed:
+                    print(f"  {[f'{b:02X}' for b in f]}")
+            else:
+                # fallback: print raw buffer if no valid frames found
+                print(f"Received bytes (raw): {[f'{b:02X}' for b in rx_buffer]}")
+        else:
+            print("No response from AVR.")
+
+    except serial.SerialException as e:
+        print(f"Serial communication error: {e}")
+    except Exception as e:
+        print(f"An error occurred: {e}")
+    finally:
+        if ser.is_open:
+            ser.close()
+            print("Serial port closed.")
+
+
+if __name__ == "__main__":
+    main()