update README + example

docs: Restructure README to match EmbeddedSpaceWire conventions

Author: Michal-Pogorzelec

README.md

@@ -1,120 +1,230 @@
-# Embedded-SDLP
+# EmbeddedSDLP
 
-A minimal Space Data Link Protocol (SDLP) implementation in C designed for embedded and resource-constrained space applications.
+Minimal, embedded-optimized implementation of **CCSDS Space Data Link Protocol (SDLP)** for TM (Telemetry) and TC (Telecommand) frame handling, following international standards.
 
-## Overview
+## Standards Compliance
 
-EmbeddedSDLP provides a lightweight implementation of TM (Telemetry) and TC (Telecommand) frame handling based on CCSDS standards. It's designed for use in spacecraft, CubeSats, and other space systems where code size and reliability are critical.
+- **CCSDS 132.0-B-3**: TM Space Data Link Protocol
+- **CCSDS 232.0-B-4**: TC Space Data Link Protocol
 
 ## Features
 
+### Core Protocol Implementation
+
 - **Telemetry (TM) Frame Handling**: Create, encode, and decode TM frames with CRC validation
 - **Telecommand (TC) Frame Handling**: Create, encode, and decode TC frames with CRC validation
-- **Minimal Dependencies**: Pure C99 with no external dependencies
-- **Embedded-Friendly**: Small memory footprint and predictable behavior
 - **CRC16 Error Detection**: Built-in frame error control field (FECF) for data integrity
 - **Configurable**: Support for virtual channels, spacecraft IDs, and frame sequence numbers
+- **TC Segment Header**: Optional MAP-based segmentation support (enabled with `TC_SEGMENT_HEADER_ENABLED`)
+
+### Design Principles
+
+- **Minimal footprint**: Small library size (stripped)
+- **Zero allocation**: Stack-based, no dynamic memory
+- **Embedded-optimized**: Pure C99, no external dependencies
+- **Portable**: Standard C99, big-endian network byte order
+- **Reliable**: CRC-16-CCITT frame error control
+
+## Project Structure
+
+```
+EmbeddedSDLP/
+├── include/
+│   ├── sdlp_common.h    # Common definitions and CRC
+│   ├── sdlp_tm.h        # TM frame definitions
+│   └── sdlp_tc.h        # TC frame definitions
+├── src/
+│   ├── sdlp_common.c    # CRC16 implementation
+│   ├── sdlp_tm.c        # TM frame implementation
+│   └── sdlp_tc.c        # TC frame implementation
+├── examples/
+│   ├── tm_example.c     # TM frame example
+│   └── tc_example.c     # TC frame example
+├── docs/
+│   ├── 132x0b3_TM_SDLP.pdf   # CCSDS 132.0-B-3 standard
+│   └── 232x0b4e1c1_TC_SDLP.pdf # CCSDS 232.0-B-4 standard
+├── Makefile
+└── README.md
+```
 
 ## Building
 
-Build the library and examples using Make:
+### Build Everything
 
 ```bash
-make all        # Build library and examples
-make lib        # Build library only
-make examples   # Build examples only
-make test       # Run example programs
-make clean      # Clean build artifacts
+make all
 ```
 
 This will create:
 - `libsdlp.a` - Static library
 - `bin/tm_example` - TM frame example
 - `bin/tc_example` - TC frame example
 
-## Usage
+### Build Library Only
+
+```bash
+make lib
+# Produces: libsdlp.a (static)
+```
+
+### Build Examples
+
+```bash
+make examples
+```
 
-### Telemetry (TM) Example
+### Run Tests
+
+```bash
+make test
+```
+
+### Clean
+
+```bash
+make clean      # Remove build artifacts
+```
+
+## Quick Start
+
+### Create and Send a TM Frame
 
 ```c
 #include "sdlp_tm.h"
 
-sdlp_tm_frame_t frame;
 uint8_t buffer[1500];
 size_t encoded_size;
 
 // Create a TM frame
-const char *data = "Temperature: 25C";
+const char *data = "Temperature: 25C, Voltage: 3.3V";
+sdlp_tm_frame_t frame;
 sdlp_tm_create_frame(&frame, 0x123, 2, (uint8_t *)data, strlen(data));
 
 // Encode frame to buffer
-sdlp_tm_encode_frame(&frame, buffer, sizeof(buffer), &encoded_size);
+if (sdlp_tm_encode_frame(&frame, buffer, sizeof(buffer), &encoded_size) == SDLP_SUCCESS) {
+    printf("TM frame encoded: %zu bytes\n", encoded_size);
+}
+```
+
+### Parse an Incoming TM Frame
 
-// Decode frame from buffer
+```c
 sdlp_tm_frame_t decoded;
-sdlp_tm_decode_frame(buffer, encoded_size, &decoded);
+if (sdlp_tm_decode_frame(buffer, encoded_size, &decoded) == SDLP_SUCCESS) {
+    printf("Spacecraft ID: 0x%03X, Data: %.*s\n",
+           decoded.header.spacecraft_id,
+           (int)decoded.data_length, decoded.data);
+}
 ```
 
-### Telecommand (TC) Example
+### Create and Send a TC Frame
 
 ```c
 #include "sdlp_tc.h"
 
-sdlp_tc_frame_t frame;
+/* Telecommand identifiers */
+#define TC_CMD_SET_MODE_SAFE  0x01U
+
 uint8_t buffer[1500];
 size_t encoded_size;
 
-// Create a TC frame
-const char *cmd = "ENABLE_SENSOR";
-sdlp_tc_create_frame(&frame, 0x456, 1, 0, (uint8_t *)cmd, strlen(cmd));
+// Create a TC frame with a numeric command ID
+uint8_t cmd_id = TC_CMD_SET_MODE_SAFE;
+sdlp_tc_frame_t frame;
+sdlp_tc_create_frame(&frame, 0x123, 1, 42, &cmd_id, sizeof(cmd_id));
 
 // Encode frame to buffer
-sdlp_tc_encode_frame(&frame, buffer, sizeof(buffer), &encoded_size);
+if (sdlp_tc_encode_frame(&frame, buffer, sizeof(buffer), &encoded_size) == SDLP_SUCCESS) {
+    printf("TC frame encoded: %zu bytes\n", encoded_size);
+}
+```
 
-// Decode frame from buffer
+### Parse an Incoming TC Frame
+
+```c
 sdlp_tc_frame_t decoded;
-sdlp_tc_decode_frame(buffer, encoded_size, &decoded);
+if (sdlp_tc_decode_frame(buffer, encoded_size, &decoded) == SDLP_SUCCESS) {
+    printf("Spacecraft ID: 0x%03X, Command ID: 0x%02X\n",
+           decoded.header.spacecraft_id,
+           decoded.data[0]);
+}
 ```
 
-## API Overview
+## API Reference
+
+### Common
 
-### Common Functions
-- `sdlp_crc16()` - Calculate CRC16 checksum
+```c
+// Calculate CRC-16-CCITT checksum
+uint16_t sdlp_crc16(const uint8_t *data, size_t length);
+```
 
 ### TM Functions
-- `sdlp_tm_create_frame()` - Create a TM frame with data
-- `sdlp_tm_encode_frame()` - Encode frame to byte buffer
-- `sdlp_tm_decode_frame()` - Decode frame from byte buffer
+
+```c
+// Create a TM frame with payload data
+int sdlp_tm_create_frame(sdlp_tm_frame_t *frame, uint16_t spacecraft_id,
+                          uint8_t virtual_channel_id, const uint8_t *data,
+                          uint16_t data_length);
+
+// Encode a TM frame into a byte buffer
+int sdlp_tm_encode_frame(const sdlp_tm_frame_t *frame, uint8_t *buffer,
+                          size_t buffer_size, size_t *encoded_size);
+
+// Decode a TM frame from a byte buffer (validates CRC)
+int sdlp_tm_decode_frame(const uint8_t *buffer, size_t buffer_size,
+                          sdlp_tm_frame_t *frame);
+```
 
 ### TC Functions
-- `sdlp_tc_create_frame()` - Create a TC frame with data
-- `sdlp_tc_encode_frame()` - Encode frame to byte buffer
-- `sdlp_tc_decode_frame()` - Decode frame from byte buffer
 
-All functions return `SDLP_SUCCESS` (0) on success or a negative error code on failure.
+```c
+// Create a TC frame with command data
+int sdlp_tc_create_frame(sdlp_tc_frame_t *frame, uint16_t spacecraft_id,
+                          uint8_t virtual_channel_id, uint8_t frame_seq_num,
+                          const uint8_t *data, uint16_t data_length);
+
+// Encode a TC frame into a byte buffer
+int sdlp_tc_encode_frame(const sdlp_tc_frame_t *frame, uint8_t *buffer,
+                          size_t buffer_size, size_t *encoded_size);
+
+// Decode a TC frame from a byte buffer (validates CRC)
+int sdlp_tc_decode_frame(const uint8_t *buffer, size_t buffer_size,
+                          sdlp_tc_frame_t *frame);
+
+// Set TC segment header fields (requires TC_SEGMENT_HEADER_ENABLED)
+int sdlp_tc_set_segment_header(sdlp_tc_frame_t *frame,
+                                sdlp_tc_seq_flag_t sequence_flags, uint8_t map_id);
+```
 
-## Project Structure
+All functions return `SDLP_SUCCESS` (0) on success or a negative error code on failure:
+- `SDLP_ERROR_INVALID_PARAM` (-1): NULL pointer or invalid parameter
+- `SDLP_ERROR_BUFFER_TOO_SMALL` (-2): Output buffer too small
+- `SDLP_ERROR_INVALID_FRAME` (-3): Frame structure invalid
+- `SDLP_ERROR_CRC_MISMATCH` (-4): CRC validation failed
 
-```
-.
-├── include/          # Header files
-│   ├── sdlp_common.h # Common definitions and CRC
-│   ├── sdlp_tm.h     # TM frame definitions
-│   └── sdlp_tc.h     # TC frame definitions
-├── src/              # Implementation files
-│   ├── sdlp_common.c
-│   ├── sdlp_tm.c
-│   └── sdlp_tc.c
-├── examples/         # Example programs
-│   ├── tm_example.c
-│   └── tc_example.c
-└── Makefile          # Build configuration
-```
+## Memory Usage (Estimated)
+
+- **Library (stripped)**: < 5 KB
+- **Per TM frame buffer**: `TM_PRIMARY_HEADER_SIZE` (6) + data + 2 bytes FECF
+- **Per TC frame buffer**: `TC_PRIMARY_HEADER_SIZE` (5) + data + 2 bytes FECF
+- **Maximum data per frame**: 1024 bytes (`TM_MAX_DATA_SIZE` / `TC_MAX_DATA_SIZE`)
+
+## Limitations and Extensions
+
+Current implementation focuses on core protocol features:
+
+- No automatic retransmission handling
+- No flow control or bandwidth management
+- No segmentation beyond optional TC segment header
+- Single static frame counter (not thread-safe)
+
+These can be extended as needed for specific mission requirements.
 
-## Requirements
+## References
 
-- C compiler with C99 support (gcc, clang, etc.)
-- Make
+- CCSDS 132.0-B-3: TM Space Data Link Protocol ([docs/132x0b3_TM_SDLP.pdf](docs/132x0b3_TM_SDLP.pdf))
+- CCSDS 232.0-B-4: TC Space Data Link Protocol ([docs/232x0b4e1c1_TC_SDLP.pdf](docs/232x0b4e1c1_TC_SDLP.pdf))
 
 ## License
 

examples/tc_example.c

@@ -1,7 +1,9 @@
 #include <stdio.h>
-#include <string.h>
 #include "sdlp_tc.h"
 
+/* Example telecommand identifiers */
+#define TC_CMD_SET_MODE_SAFE  0x01U
+
 int main(void) {
     sdlp_tc_frame_t frame;
     uint8_t buffer[1500];
@@ -10,7 +12,7 @@ int main(void) {
 
     printf("=== TC Frame Example ===\n\n");
 
-    const char *command_data = "SET_MODE SAFE";
+    uint8_t cmd_id = TC_CMD_SET_MODE_SAFE;
     uint16_t spacecraft_id = 0x123;
     uint8_t virtual_channel = 1;
     uint8_t sequence_number = 42;
@@ -19,11 +21,10 @@ int main(void) {
     printf("Spacecraft ID: 0x%03X\n", spacecraft_id);
     printf("Virtual Channel: %d\n", virtual_channel);
     printf("Sequence Number: %d\n", sequence_number);
-    printf("Command: %s\n", command_data);
+    printf("Command ID: 0x%02X\n", cmd_id);
 
     result = sdlp_tc_create_frame(&frame, spacecraft_id, virtual_channel,
-                                   sequence_number, (const uint8_t *)command_data,
-                                   strlen(command_data));
+                                   sequence_number, &cmd_id, sizeof(cmd_id));
 
     if (result != SDLP_SUCCESS) {
         printf("Error creating frame: %d\n", result);
@@ -73,7 +74,7 @@ int main(void) {
     printf("Segment Header: sequence_flags=0x%X map_id=%d\n",
            decoded_frame.segment_header.sequence_flags, decoded_frame.segment_header.map_id);
 #endif
-    printf("Command: %.*s\n", (int)decoded_frame.data_length, decoded_frame.data);
+    printf("Command ID: 0x%02X\n", decoded_frame.data[0]);
     printf("CRC: 0x%04X\n", decoded_frame.fecf);
 
     printf("\n=== TC Frame Example Complete ===\n");