_INVALID_DATA;
}
```
**TRY Macro Usage:**
The implementation uses a `TRY()` macro for error propagation (from result.h):
```c
// In validate_imu_data()
result_t validate_imu_data(float accel_x, float accel_y, float accel_z) {
TRY(validate_accelerometer_value(accel_x)); // Return on error
TRY(validate_accelerometer_value(accel_y)); // Return on error
TRY(validate_accelerometer_value(accel_z)); // Return on error
return RESULT_OK;
}
```
---
## Implementation Status
**Currently Implemented (Active):**
- ✓ validate\_ph\_value()
- ✓ validate\_accelerometer\_value()
- ✓ validate\_imu\_data()
- ✓ validate\_gps\_latitude()
- ✓ validate\_gps\_longitude()
- ✓ validate\_gps\_hdop()
- ✓ validate\_gps\_satellite\_count()
**Currently Commented Out (Inactive):**
- ⊘ celsius\_to\_fahrenheit() - Declared but not implemented
- ⊘ fahrenheit\_to\_celsius() - Declared but not implemented
- ⊘ bar\_to\_psi() - Declared but not implemented
- ⊘ psi\_to\_bar() - Declared but not implemented
**Note:** Temperature and pressure conversions are stubbed out in the current implementation. They can be enabled by uncommenting the implementation in sensor\_basics.c if needed for future features.
---
## Testing
**Test Suite Location:** `test/sensor_board/test_sensor_basics/`
**Building Tests:**
```bash
// Run all sensor_basics tests
pio test -e sensor_board -f test_sensor_basics
// Run with verbose output
pio test -e sensor_board -f test_sensor_basics -v
```
**Test Coverage:**
- Boundary value testing (min/max ranges)
- Edge cases (0 values, extreme values)
- Valid range acceptance
- Invalid range rejection
- NULL pointer handling for conversion functions
---
## Integration in Main Application
**Typical Usage in main.c:**
```c
// After polling a sensor
result_t poll_result = poll_gps_sensor(&gps_data);
if (poll_result == RESULT_OK) {
// Validate all GPS fields before using
if (validate_gps_latitude(gps_data.latitude) == RESULT_OK &&
validate_gps_longitude(gps_data.longitude) == RESULT_OK) {
diagnostics.gps_sensor_1.state = SENSOR_OPERATING;
// Safe to use: gps_data.latitude, gps_data.longitude
} else {
diagnostics.gps_sensor_1.state = SENSOR_ERROR;
diagnostics.gps_sensor_1.error_code = GPS_INVALID_DATA;
}
} else if (poll_result == RESULT_ERR_COMMS) {
diagnostics.gps_sensor_1.state = SENSOR_ERROR;
diagnostics.gps_sensor_1.error_code = GPS_COMMUNICATION_FAILURE;
}
```
# Architecture
Complete system overview showing FreeRTOS, sensor polling loop, protobuf encoding, UDP transmission, and memory layout. Includes initialization sequence and error handling strategy.
## Main Loop Operation
```c
while (1) {
// STEP 1: System Health Check
// - Check heap (critical: <8KB)
// - Toggle status LEDs
// - Send raw Ethernet beacon
// STEP 2: Initialize Diagnostics Message
SensorBoardDiagnostics diagnostics_msg;
// STEP 3: Poll All Sensors
// - pH Sensor
// - GPS Sensor
// - IMU Sensor
// - Load Cells (x2)
// - Pressure Sensors (x2)
// STEP 4: Encode & Transmit
// - Encode diagnostics to Protobuf
// - Send UDP broadcast (192.168.0.255:7)
// STEP 5: Wait
osDelay(5000); // 5 seconds
}
```
## Error Handling Strategy
### Polling Error States
```c
if (poll_result == RESULT_ERR_UNIMPLEMENTED) {
sensor.state = SENSOR_IDLE;
sensor.error_code = COMMUNICATION_FAILURE;
} else if (poll_result == RESULT_ERR_COMMS) {
sensor.state = SENSOR_ERROR;
sensor.error_code = COMMUNICATION_FAILURE;
} else if (poll_result == RESULT_OK) {
if (validate_sensor_data(value) == RESULT_OK) {
sensor.state = SENSOR_OPERATING;
sensor.error_code = NO_ERROR;
} else {
sensor.state = SENSOR_ERROR;
sensor.error_code = INVALID_DATA;
}
}
```
### Sensor Status Codes
| Code
| Meaning
|
|---|
| `SENSOR_IDLE`
| Not connected or not implemented
|
| `SENSOR_OPERATING`
| Normal operation, valid data
|
| `SENSOR_ERROR`
| Communication failure or invalid data
|
## Initialization Sequence
### Phase 1: Hardware Setup
```
1. MPU/Cache configuration
2. HAL initialization
3. System clock → 480 MHz
4. RTOS kernel init
5. GPIO initialization
6. Timer initialization (TIM1)
```
### Phase 2: Communication Setup
```
1. UART initialization (115200 baud)
2. Logging system init
3. Ethernet PHY init (LAN8742)
4. MAC address filtering
5. ARP table setup
```
### Phase 3: Application Setup
```
1. Packet dispatcher registration
2. Sensor initialization
3. UDP queue creation
4. UDP callback registration
```
### Phase 4: Main Loop
```
1. LED initialization
2. Sensor polling starts
3. Continuous 5-second cycles
```
```
```
# Configuration
Compile-time parameters, runtime configuration, sensor calibration setup, network addressing, UDP ports, performance tuning options
#### UDP Configuration
```c
// In src/sensor_board/main.c
#define SENSOR_UDP_DEST_PORT 7
uint8_t dest_ip[4] = {192, 168, 0, 255}; // Broadcast address
```
#### Main Loop Timing
```c
// In src/sensor_board/main.c
#define MAIN_TASK_DELAY_MS 5000 // 5 seconds between updates
```
#### Heap Management
```c
// Critical heap threshold
#define CRITICAL_HEAP_THRESHOLD 8192 // 8 KB minimum
```
#### Task Configuration
```c
const osThreadAttr_t mainTask_attributes = {
.name = "mainTask",
.stack_size = 1024 * 8, // 8 KB stack
.priority = (osPriority_t)osPriorityNormal,
};
```
## Runtime Configuration
### Changing Sensor Poll Interval
```c
// Current: 5 seconds
#define MAIN_TASK_DELAY_MS 5000
// Change to 1 second
#define MAIN_TASK_DELAY_MS 1000
// Change to 10 seconds
#define MAIN_TASK_DELAY_MS 10000
```
### Enabling/Disabling Sensors
```c
// Current: skip all sensor polling during development
const bool skip_sensor_polling = true;
// To ENABLE actual polling:
const bool skip_sensor_polling = false;
// To SKIP (for testing without hardware):
const bool skip_sensor_polling = true;
```
### Adjusting Heap Threshold
```c
// Current: 8 KB critical
if (free_heap < 8192) {
LOGE(TAG, "CRITICAL: Low heap detected! Free: %lu bytes", free_heap);
}
```
## Sensor Calibration Configuration
### pH Sensor Calibration
```c
// Set reference voltage (typically 3.3V or 5.0V)
ph_sensor_init(&ph_sensor, 3.3f); // 3.3V reference
// Update calibration (after two-point calibration)
ph_sensor.calibration.offset = 0.0f; // Adjust after pH 7.0 test
ph_sensor.calibration.slope = 3.5f; // Adjust after second pH test
```
### Load Cell Calibration
```c
// After tare (no load):
load_cell_data[0].tare_offset_counts = adc_reading_no_load;
// After known weight measurement:
// scale = (force_newtons) / (adc_reading - tare_offset)
load_cell_data[0].scale_newtons_per_count = scale_factor;
load_cell_data[0].is_calibrated = true;
```
## Network Configuration
### Changing Broadcast Address
```c
//To be implemented
```
### Changing UDP Port
```c
//To be implemented
```
# GNSS
Global positioning module with NMEA 0183 protocol support. Contains data structures, initialization code, validation functions, and UART configuration for the GY-NEO6MV2 sensor.
### Hardware Specifications
| Parameter
| Value
|
|---|
| Model
| GY-NEO6MV2 (NEO-6M)
|
| Interface
| UART (TTL serial)
|
| Baud Rate
| 9600 bps
|
| Protocol
| NMEA 0183
|
| Update Rate
| 1 Hz (configurable)
|
### GPS Fix Quality Types
```c
typedef enum {
GPS_NO_FIX = 0, // No GPS fix available
GPS_GPS_FIX = 1, // Standard GPS fix
GPS_DGPS_FIX = 2, // Differential GPS fix
GPS_PPS_FIX = 3, // PPS (Pulse Per Second) fix
GPS_RTK_FIX = 4, // Real-Time Kinematic fix
GPS_RTK_FLOAT = 5 // RTK float solution
} gps_fix_quality_t;
```
## Data Structure
```c
typedef struct {
// Position Data
double latitude; // ±90 degrees (North/South)
double longitude; // ±180 degrees (East/West)
float altitude; // Meters above sea level
// Velocity & Direction
float speed; // Meters per second
float heading; // 0-360 degrees (course over ground)
// Accuracy Indicators
float hdop; // Horizontal dilution of precision
float vdop; // Vertical dilution of precision
int32_t satellites; // Number of satellites in view
gps_fix_quality_t fix_quality;
// Timestamps
int64_t utc_timestamp; // Unix epoch (milliseconds)
uint32_t timestamp; // System timestamp (last reading)
uint32_t last_timestamp; // System timestamp (previous reading)
// Status
bool is_valid; // Data validity flag
// UART Parsing State
char rx_buffer[256]; // UART receive buffer
uint16_t rx_index; // Current buffer position
bool sentence_ready; // Complete sentence available
} gps_data_t;
```
### NMEA Sentences Supported
| Sentence
| Purpose
|
|---|
| **GGA**
| Fix data (time, position, fix quality, satellite count)
|
| **RMC**
| Recommended Min. Navigation Info (position, speed, heading, date)
|
| **GSA**
| DOP and active satellites (fix type, DOP values)
|
## Initialization & Usage
### Initialize GPS
```c
gps_data_t gps_data;
gps_sensor_init(&gps_data);
```
### Poll GPS Data
```c
result_t gps_poll_result = poll_gps_sensor(&gps_data);
if (gps_poll_result == RESULT_OK) {
double latitude = gps_data.latitude;
double longitude = gps_data.longitude;
float altitude = gps_data.altitude;
int32_t satellites = gps_data.satellites;
float hdop = gps_data.hdop;
}
```
## Validation Functions
```c
// Validate latitude (-90 to +90)
result_t validate_gps_latitude(double latitude);
// Validate longitude (-180 to +180)
result_t validate_gps_longitude(double longitude);
// Validate HDOP (horizontal dilution of precision)
// Typical range: 0-50
result_t validate_gps_hdop(float hdop);
// Validate satellite count
// Typical: 0-30 satellites
result_t validate_gps_satellite_count(int32_t satellites);
```
## Protobuf Message Format
```protobuf
message SensorBoardGPSInfo {
double latitude;
double longitude;
float altitude;
float speed;
float heading;
float hdop;
float vdop;
int32 satellites;
SensorState state;
GPSErrorCode error_code;
}
```
## Error Handling
```c
if (gps_poll_result == RESULT_ERR_UNIMPLEMENTED) {
// Hardware not connected
diagnostics.gps_sensor_1.state = SensorState_SENSOR_IDLE;
diagnostics.gps_sensor_1.error_code = GPSErrorCode_GPS_COMMUNICATION_FAILURE;
} else if (gps_poll_result == RESULT_ERR_COMMS) {
// Communication error (timeout/CRC)
diagnostics.gps_sensor_1.state = SensorState_SENSOR_ERROR;
} else if (gps_poll_result == RESULT_OK) {
// Validate data before accepting
if (validate_gps_latitude(gps_data.latitude) == RESULT_OK) {
diagnostics.gps_sensor_1.state = SensorState_SENSOR_OPERATING;
}
}
```
## Integration Notes
- Configured for dual GPS redundancy capability
- UART buffer size: 256 bytes
- NMEA sentence max length: 83 characters
- Data published to network at main loop interval (5 seconds default)
- All GPS data transmitted via UDP with Protobuf encoding
- Temperature range: -40°C to +85°C (standard)
# pH Sensor
The pH sensor provides water quality measurement critical for environmental monitoring and anomaly detection.
### Hardware Specifications
| Parameter
| Value
|
|---|
| Model
| DFRobot SEN0161 (Analog pH meter)
|
| Interface
| Analog ADC
|
| Reference Voltage
| 3.3V or 5.0V (configurable)
|
| Output Range
| 0-5V analog
|
| Measurement Range
| 0-14 pH units
|
| Accuracy
| ±0.1 pH @ 25°C
|
| Sample Rate
| Configurable (40 samples for averaging)
|
## Calibration Model
The sensor uses linear voltage-to-pH conversion:
```
pH = (Voltage / Reference_Voltage) × Slope + Offset
```
**Default Parameters for SEN0161** @ 25°C:
- **Slope**: 3.5
- **Offset**: Variable (user calibration)
## Data Structure
```c
typedef struct {
// Raw ADC Reading
uint16_t raw_value; // Raw ADC value
// Calculated Values
float voltage; // Converted voltage (0-5V)
float ph_value; // Calculated pH (0-14)
float reference_voltage; // ADC reference (typically 3.3V or 5.0V)
// Calibration Parameters
ph_calibration_t calibration; // { offset: float, slope: float }
// Averaging Buffer (Noise Filtering)
uint16_t sample_buffer[40]; // Last 40 samples
uint8_t sample_index; // Current position in buffer
uint8_t samples_collected; // Total samples collected (0-40)
} ph_sensor_t;
```
## Initialization & Usage
### Initialize pH Sensor
```c
ph_sensor_t ph_sensor;
ph_sensor_init(&ph_sensor, 3.3f); // 3.3V reference voltage
```
### Poll pH Sensor
```c
result_t ph_result = poll_ph_sensor(&ph_sensor);
if (ph_result == RESULT_OK) {
float ph_value = ph_sensor.ph_value;
float voltage = ph_sensor.voltage;
}
```
### Manual Sample Addition
```c
// For manual sampling at regular intervals
uint16_t adc_reading = 2048; // Example ADC value
ph_sensor_add_sample(&ph_sensor, adc_reading);
```
## Validation
```c
result_t validate_ph_value(float ph_value);
// Returns RESULT_OK if 0 <= ph_value <= 14
// Returns RESULT_ERR_INVALID_DATA otherwise
```
## Sample Averaging Strategy
| Parameter
| Value
|
|---|
| Sample Buffer Size
| 40 samples
|
| Method
| Circular buffer moving average
|
| Purpose
| Noise filtering and stable readings
|
| Typical Update Latency
| 40ms-800ms
|
### Averaging Algorithm
```
1. ADC sample added to circular buffer
2. All 40 samples averaged together
3. Averaged value converted to voltage
4. Voltage converted to pH via calibration
```
## Two-Point Calibration Procedure
### Step 1: Neutral Point (pH 7.0)
```
1. Immerse electrode in pH 7.0 buffer solution
2. Wait for stable reading (~2 minutes)
3. Record voltage: V_neutral
4. Calculate offset adjustment
```
### Step 2: Slope Calibration (pH 4.0 or 10.0)
```
1. Immerse electrode in second known pH solution
2. Wait for stable reading
3. Record voltage: V_reference
4. Calculate slope from two points:
slope = (pH_reference - 7.0) / (V_reference - V_neutral)
```
## Protobuf Message Format
```protobuf
message SensorBoardPHInfo {
float ph_value;
float voltage;
SensorState state;
PHErrorCode error_code;
}
enum PHErrorCode {
PH_NO_ERROR = 0;
PH_COMMUNICATION_FAILURE = 1;
PH_INVALID_DATA = 2;
}
```
## Error Handling
```c
if (ph_result == RESULT_ERR_UNIMPLEMENTED) {
// Hardware not connected
diagnostics.ph_sensor.state = SensorState_SENSOR_IDLE;
diagnostics.ph_sensor.error_code = PHErrorCode_PH_COMMUNICATION_FAILURE;
} else if (ph_result == RESULT_OK) {
if (validate_ph_value(ph_sensor.ph_value) == RESULT_OK) {
diagnostics.ph_sensor.state = SensorState_SENSOR_OPERATING;
diagnostics.ph_sensor.error_code = PHErrorCode_PH_NO_ERROR;
} else {
// Invalid data from sensor (out of 0-14 range)
diagnostics.ph_sensor.state = SensorState_SENSOR_ERROR;
diagnostics.ph_sensor.error_code = PHErrorCode_PH_INVALID_DATA;
}
}
```
## Integration Notes
- Single sensor instance in main application
- Updates transmitted to network at main loop interval (5 seconds default)
- Temperature compensation not currently implemented (assumes ~25°C)
- Sample averaging reduces noise but introduces ~40ms latency per update
- Electrode response time: ~100-300ms depending on pH change magnitude
# IMU
The Inertial Measurement Unit (IMU) provides three-axis acceleration, angular velocity, and magnetic field measurements for attitude determination and motion analysis.
### Communication Interfaces
- **Accelerometer**: I2C or SPI
- **Gyroscope**: I2C or SPI
- **Magnetometer**: I2C or SPI
- **Update Rate**: Typically 1-100+ Hz (configurable)
## Data Structure
```c
typedef struct {
// Acceleration (m/s² or g-units)
float accel[3]; // [X, Y, Z] acceleration
// Angular Velocity (rad/s or °/s)
float gyro[3]; // [X, Y, Z] rotation rate
// Magnetic Field (Gauss or µT)
float mag[3]; // [X, Y, Z] magnetic field
// Timestamps
uint32_t timestamp; // Current reading timestamp
uint32_t last_timestamp; // Previous reading timestamp
} imu_data_t;
```
## Initialization & Usage
### Initialize IMU
```c
imu_data_t imu_data;
imu_sensor_init(&imu_data);
```
### Poll IMU Data
```c
result_t imu_result = poll_imu_sensor(&imu_data);
if (imu_result == RESULT_OK) {
// Acceleration
float accel_x = imu_data.accel[0];
float accel_y = imu_data.accel[1];
float accel_z = imu_data.accel[2];
// Angular velocity
float gyro_x = imu_data.gyro[0];
float gyro_y = imu_data.gyro[1];
float gyro_z = imu_data.gyro[2];
// Magnetic field
float mag_x = imu_data.mag[0];
float mag_y = imu_data.mag[1];
float mag_z = imu_data.mag[2];
}
```
## Advanced Functions
### Update with Raw Values
```c
result_t imu_sensor_update(
imu_data_t *imu,
float ax, float ay, float az, // Accelerometer values
float gx, float gy, float gz, // Gyroscope values
float mx, float my, float mz, // Magnetometer values
uint32_t timestamp
);
```
### Calculate Acceleration Magnitude
```c
float acceleration_magnitude = imu_get_acceleration_magnitude(&imu_data);
// Useful for impact detection and free-fall detection
```
### Thread-Safe Data Reading
```c
imu_data_t imu_copy;
imu_sensor_read(&imu_data, &imu_copy);
// Use imu_copy in another thread without locking
```
## Typical Sensor Ranges
| Measurement
| Typical Range
| Units
|
|---|
| Acceleration
| ±16
| g
|
| Angular Velocity
| ±2000
| °/s
|
| Magnetic Field
| ±4800
| µT
|
### Conversion Reference
| From
| To
| Factor
|
|---|
| g
| m/s²
| × 9.81
|
| °/s
| rad/s
| × π/180
|
| Gauss
| µT
| × 100
|
## Validation Functions
```c
// Validate single accelerometer value
// Typical range: -50 to +50 m/s2
result_t validate_accelerometer_value(float accel_value);
// Validate all three acceleration axes
result_t validate_imu_data(
float accel_x,
float accel_y,
float accel_z
);
```
## Protobuf Message Format
```protobuf
message SensorBoardIMUInfo {
float accel_x;
float accel_y;
float accel_z;
float gyro_x;
float gyro_y;
float gyro_z;
SensorState state;
}
```
## Common Applications
### Impact Detection
```c
float mag = imu_get_acceleration_magnitude(&imu_data);
if (mag > IMPACT_THRESHOLD) {
// High acceleration detected
}
```
### Tilt Detection
```c
// Calculate tilt angle from acceleration
float tilt_angle = atan2(imu_data.accel[0], imu_data.accel[2]);
```
### Motion Classification
```c
// Static vs dynamic based on gyro magnitude
float gyro_mag = sqrt(gyro_x*gyro_x + gyro_y*gyro_y + gyro_z*gyro_z);
```
## Integration Notes
- Single IMU instance with 3-axis sensors (dual planned)
- All three axes transmitted as independent fields
- Acceleration magnitude available for impact detection
- Timestamp tracking enables dead reckoning applications
- Typical IMU update rate: 10-100 Hz
- Filter algorithms can be applied to raw data for smoothing
# Load Cell
Load cells measure force/weight to detect object presence, evaluate structural loading, or monitor mechanical stress. The system supports dual load cell configuration.
### Hardware Specifications
| Parameter
| Value
|
|---|
| Sensor Count
| 2 (independent)
|
| Interface
| Analog ADC
|
| Measurement
| Force (Newtons) / Mass (grams)
|
| Update Rate
| Configurable
|
## Data Structure
```c
typedef struct {
// Raw Reading
int32_t raw_counts; // ADC value from sensor
// Converted Measurements
float force_newtons; // Force in Newtons (N)
float mass_grams; // Equivalent mass in grams (g)
// Calibration Parameters
float scale_newtons_per_count; // Conversion factor (N/count)
int32_t tare_offset_counts; // Zero-load ADC offset
// Status
bool is_calibrated; // Calibration valid flag
} load_cell_data_t;
```
## Initialization
### Initialize Load Cells
```c
load_cell_data_t load_cell_data[2]; // Support 2 sensors
for (size_t i = 0; i < 2; i++) {
load_cell_sensor_init(&load_cell_data[i]);
}
```
### Poll Load Cell Sensor
```c
result_t lc_result = poll_load_cell_sensor(&load_cell_data[0]);
if (lc_result == RESULT_OK) {
float force = load_cell_data[0].force_newtons;
float mass = load_cell_data[0].mass_grams;
int32_t raw = load_cell_data[0].raw_counts;
}
```
## Data Access Functions
```c
// Get force in Newtons
result_t load_cell_get_force_newtons(
const load_cell_data_t *data,
float *force_newtons
);
// Get mass in grams (estimated)
result_t load_cell_get_mass_grams(
const load_cell_data_t *data,
float *mass_grams
);
// Get raw ADC counts
result_t load_cell_get_raw_counts(
const load_cell_data_t *data,
int32_t *raw_counts
);
// Get calibration parameters
result_t load_cell_get_calibration(
const load_cell_data_t *data,
float *scale_newtons_per_count,
int32_t *tare_offset_counts
);
// Verify sensor validity
result_t load_cell_sensor_is_valid(
const load_cell_data_t *data,
bool *is_valid
);
```
## Calibration Procedure
### Two-Step Calibration
#### Step 1: Tare (Zero Load)
```
1. Remove all load from sensor
2. Measure ADC value: ADC_zero
3. Set tare_offset_counts = ADC_zero
```
#### Step 2: Span (Known Weight)
```
1. Place known weight on sensor
2. Measure ADC value: ADC_loaded
3. Know reference force: F_ref (Newtons)
4. Calculate scale:
scale = (F_ref - 0.0) / (ADC_loaded - ADC_zero)
5. Set scale_newtons_per_count = scale
```
### Measurement Formulas
```c
// Raw force calculation
Force = (raw_counts - tare_offset_counts) × scale_newtons_per_count
// Mass conversion (approximate)
Mass_grams = (Force_newtons / 9.81) × 1000
≈ Force_newtons × 102.04
```
## Dual Sensor Management
### Configuration Example
```c
// Initialize both sensors
for (size_t i = 0; i < 2; i++) {
load_cell_sensor_init(&load_cell_data[i]);
}
// Poll both in sequence
poll_load_cell_sensor(&load_cell_data[0]);
poll_load_cell_sensor(&load_cell_data[1]);
// Access by index
float load_0 = load_cell_data[0].force_newtons;
float load_1 = load_cell_data[1].force_newtons;
```
## Protobuf Message Format
```protobuf
message SensorBoardLoadCellInfo {
uint32 sensor_index; // 0 or 1
float force_newtons;
float mass_grams;
SensorState state;
LoadCellErrorCode error_code;
}
```
## Unit Conversions
| From
| To
| Factor
|
|---|
| Newtons
| kilograms-force (kgf)
| ÷ 9.81
|
| Newtons
| pounds-force (lbf)
| ÷ 4.448
|
| grams
| kilograms
| ÷ 1000
|
### Manual Unit Conversion Example
```c
// Convert to pounds-force
float force_lbf = load_cell_data[0].force_newtons / 4.448f;
// Convert to kilograms
float mass_kg = load_cell_data[0].mass_grams / 1000.0f;
```
## Typical Specifications
| Load Cell Type
| Max Load
| Accuracy
|
|---|
| Strain gauge (±50N)
| 50N
| ±0.1%
|
| Load cell (±100N)
| 100N
| ±0.05%
|
| Heavy duty (±1000N)
| 1000N
| ±0.1%
|
## Integration Notes
- Supports up to 2 independent load cell sensors
- Hardware-specific ADC implementation
- Force conversion via linear scaling model
- Tare offset corrects for sensor mechanical zero
- Real-time monitoring of structural loads
- Each sensor maintains separate calibration
- Independent error reporting per sensor
# Pressure Sensor
Pressure sensors measure fluid/gas pressure for robotic gripper force feedback and control, depth sensing, altitude measurement, or system pressure monitoring. The system supports dual pressure sensor configuration for dual-pad gripper control with load distribution feedback.
### Hardware Specifications
| Parameter
| Value
|
|---|
| Sensor Count
| 2 (independent)
|
| Interface
| Analog ADC or I2C
|
| Measurement Range
| Variable (typically 0-300 kPa)
|
| Update Rate
| Configurable
|
## Data Structure
```c
typedef struct {
float pressure_kpa; // Pressure in kilopascals (kPa)
float temperature_c; // Temperature in Celsius (°C)
float voltage; // Sensor output voltage
bool is_calibrated; // Calibration status flag
} pressure_sensor_data_t;
```
## Initialization
### Initialize Pressure Sensors
```c
pressure_sensor_data_t pressure_data[2]; // Support 2 sensors
for (size_t i = 0; i < 2; i++) {
pressure_sensor_init(&pressure_data[i]);
}
```
### Poll Pressure Sensor
```c
result_t ps_result = poll_pressure_sensor(&pressure_data[0]);
if (ps_result == RESULT_OK) {
float pressure_kpa = pressure_data[0].pressure_kpa;
float temperature_c = pressure_data[0].temperature_c;
}
```
## Data Access Functions
```c
// Get pressure in kilopascals
result_t pressure_sensor_get_pressure_kpa(
const pressure_sensor_data_t *data,
float *pressure_kpa
);
// Get temperature in Celsius
result_t pressure_sensor_get_temperature_c(
const pressure_sensor_data_t *data,
float *temperature_c
);
// Get raw sensor voltage
result_t pressure_sensor_get_voltage(
const pressure_sensor_data_t *data,
float *voltage
);
// Verify sensor validity
result_t pressure_sensor_is_valid(
const pressure_sensor_data_t *data,
bool *is_valid
);
```
## Pressure Unit Conversions
### Function-Based Conversions
```c
// Convert pressure from bar to psi
result_t bar_to_psi(float bar, float *psi);
// Convert pressure from psi to bar
result_t psi_to_bar(float psi, float *bar);
```
### Conversion Table
| From
| To
| Multiply By
|
|---|
| bar
| kPa
| 100
|
| psi
| kPa
| 6.895
|
| atm
| kPa
| 101.325
|
| kPa
| bar
| 0.01
|
| kPa
| psi
| 0.145
|
| kPa
| atm
| 0.00987
|
### Examples
```c
// 100 kPa = 1 bar
float kpa = 100.0f;
float bar = kpa * 0.01f; // Result: 1.0 bar
// 50 psi to bar
float psi = 50.0f;
float bar = psi / 14.504f; // Result: 3.45 bar
// Altitude from pressure (simplified)
// Altitude ≈ 44330 × (1 - (P/P0)^(1/5.255))
float altitude_m = 44330.0f * (1.0f - pow(pressure_kpa/101.325f, 1.0f/5.255f));
```
## Protobuf Message Format
```protobuf
message SensorBoardPressureInfo {
uint32 sensor_index; // 0 or 1
float pressure_kpa;
float temperature_c;
SensorState state;
PressureErrorCode error_code;
}
```
## Dual Sensor Management
### Configuration Example
```c
// Initialize both sensors
for (size_t i = 0; i < 2; i++) {
pressure_sensor_init(&pressure_data[i]);
}
// Poll both in sequence
poll_pressure_sensor(&pressure_data[0]);
poll_pressure_sensor(&pressure_data[1]);
// Access by index
float pressure_0_kpa = pressure_data[0].pressure_kpa;
float pressure_1_kpa = pressure_data[1].pressure_kpa;
```
## Temperature Compensation
Pressure readings often need temperature compensation for accuracy:
```c
// Simplified temperature compensation
float compensated_pressure = pressure_data[0].pressure_kpa *
(reference_temperature + 273.15f) /
(pressure_data[0].temperature_c + 273.15f);
```
## Applications
### Robotic Gripper Control (Primary Use Case)
```c
// Gripper force feedback for adaptive grip strength
// Pressure reading controls servo/motor PWM to regulate grip force
#define GRIPPER_MIN_PRESSURE_KPA 20.0f // Minimum safe grip
#define GRIPPER_MAX_PRESSURE_KPA 150.0f // Maximum allowed grip
#define GRIPPER_TARGET_PRESSURE_KPA 80.0f // Desired grip force
// PID controller for gripper force regulation
typedef struct {
float kp, ki, kd; // PID coefficients
float integral_error;
float previous_error;
} gripper_pid_t;
// Adjust servo PWM based on pressure feedback
void adjust_gripper_force(float current_pressure_kpa, gripper_pid_t *pid) {
float error = GRIPPER_TARGET_PRESSURE_KPA - current_pressure_kpa;
pid->integral_error += error;
float derivative_error = error - pid->previous_error;
float pid_output = (pid->kp * error) +
(pid->ki * pid->integral_error) +
(pid->kd * derivative_error);
// Clamp servo PWM to valid range
uint16_t servo_pwm = (uint16_t)(GRIPPER_NEUTRAL_PWM + pid_output);
servo_pwm = (servo_pwm < GRIPPER_MIN_PWM) ? GRIPPER_MIN_PWM : servo_pwm;
servo_pwm = (servo_pwm > GRIPPER_MAX_PWM) ? GRIPPER_MAX_PWM : servo_pwm;
set_gripper_pwm(servo_pwm);
pid->previous_error = error;
}
```
**Gripper Control Features:**
- Grip force feedback for object handling
- Object presence detection (pressure spike threshold)
- Adaptive compliance for varying object sizes/materials
- Dual sensors support load sharing across gripper pads
### Implemented but Not Primary
#### Depth Sensing (Water)
```c
// Pressure to depth in water
// P = ρ × g × h
// where ρ = 1025 kg/m³ (seawater), g = 9.81 m/s²
float depth_meters = (pressure_kpa - atmospheric_pressure_kpa) / 10.0f;
```
#### Altitude Sensing (Air)
```c
// Barometric formula (simplified)
float altitude_m = 44330.0f * (1.0f - pow(pressure_kpa/101.325f, 1.0f/5.255f));
```
#### System Pressure Monitoring
```c
if (pressure_kpa > PRESSURE_WARNING_THRESHOLD) {
// High pressure detected - safety alert
}
```
## Common Pressure Sensor Ranges
| Application
| Range
| Typical Sensor
|
|---|
| Altitude (aviation)
| 10-110 kPa
| BMP280/BMP390
|
| Depth (diving)
| 0-300+ kPa
| Custom depth sensor
|
| System pressure
| 0-500+ kPa
| Industrial pressure transducer
|
## Integration Notes
- **Primary Application:** Robotic gripper force feedback and control
- Supports up to 2 independent pressure sensors (dual gripper pads)
- Temperature measurement for compensation algorithms
- Hardware-specific ADC or I2C implementation
- Pressure-voltage conversion implemented internally
- Real-time depth/altitude sensing capability
- PID control loop integration for adaptive grip force
- Each sensor maintains independent calibration
- Temperature tracking for accuracy improvements
- Slip detection via pressure variance analysis
# Testing
Test organization, validation functions, Unity testing framework usage, manual hardware testing checklists and debugging/troubleshooting guide.
## Test Organization
```
test/sensor_board/
├── test_gps_sensor/
│ ├── NMEA parsing verification
│ ├── Coordinate validation
│ └── Fix quality enumeration tests
│
├── test_imu_sensor/
│ ├── 3-axis data structure tests
│ ├── Acceleration magnitude calculation
│ └── Timestamp tracking validation
│
├── test_load_sensor/
│ ├── Force calculation (tare/scale)
│ ├── Mass conversion (g/kg/lbf)
│ ├── Dual sensor independence
│ └── Calibration parameter storage
│
├── test_ph_sensor/
│ ├── ADC to voltage conversion
│ ├── pH value calculation
│ ├── Sample averaging (40-sample buffer)
│ ├── Calibration offset/slope
│ └── Edge cases (pH 0, 14)
│
├── test_pressure_sensor/
│ ├── Pressure reading validation
│ ├── Temperature compensation
│ ├── Unit conversions (bar/psi/kPa)
│ └── Dual sensor independence
│
└── test_sensor_basics/
├── Conversion functions
├── Validation functions
├── Range checking
└── Boundary conditions
```
## Validation Functions
### GPS Validation
```c
result_t validate_gps_latitude(double latitude);
// Valid range: -90.0 to +90.0 degrees
result_t validate_gps_longitude(double longitude);
// Valid range: -180.0 to +180.0 degrees
result_t validate_gps_hdop(float hdop);
// Typical range: 0.0 to 50.0
result_t validate_gps_satellite_count(int32_t satellites);
// Typical range: 0 to 30 satellites
```
### pH Validation
```c
result_t validate_ph_value(float ph_value);
// Valid range: 0.0 to 14.0
```
### IMU Validation
```c
result_t validate_accelerometer_value(float accel_value);
// Typical range: -50.0 to +50.0 m/s²
result_t validate_imu_data(float accel_x, float accel_y, float accel_z);
```
### Unit Conversion Tests(extra stuff)
```c
result_t celsius_to_fahrenheit(float celsius, float *fahrenheit);
result_t fahrenheit_to_celsius(float fahrenheit, float *celsius);
result_t bar_to_psi(float bar, float *psi);
result_t psi_to_bar(float psi, float *bar);
```
## Test Framework
### Testing Technology
- **Framework**: Unity (open-source testing framework)
- **Build System**: CMake / PlatformIO
- **Test Type**: Hosted unit tests (run on PC)
- **Mocking**: Mock ADC/UART/I2C interfaces
### Building Tests
```bash
// Build all tests
pio test -e sensor_board
// Run specific test suite
pio test -e sensor_board -f test_ph_sensor
```
## Debugging & Troubleshooting
| Issue
| Cause
| Solution
|
|---|
| Sensor IDLE
| Not connected
| Check UART/I2C/SPI wiring
|
| Sensor ERROR
| Communication failure
| Verify baud rates, addresses
|
| Invalid data
| Out of range
| Check calibration parameters
|
| Low heap warning
| Memory leak
| Review packet encoder
|
# Reference
Checkout the embedded simplified from ERC
## Source Code References
If you made it till here, you a true G. Also, this was rather useful, check this out... [ERC Embedded Simplified Official](https://creations.mtdv.me/Rick-ZarolERC-Embedded-Simplified-Official "ERC Embedded Simplified Official")
### Main Application
| File
| Purpose
|
|---|
| `src/sensor_board/main.c`
| Main entry point and sensor loop
|
### Sensor Drivers
### Protobuf Definitions
**For detailed protobuf message format documentation, see:** [Sensor Board Protobuf](https://bookstack.roboteamtwente.nl/books/communication-system/page/sensor-board-protobuf "Sensor Board Protobuf")
```
ERC-Protobufs/components/sensor_board/
├── diagnostics.proto - Board-level diagnostics and health status
├── sensor.proto - Aggregated sensor state message
├── gps_sensor.proto - GNSS positioning data
├── imu_sensor.proto - Inertial measurement (acceleration, gyro, mag)
├── ph_sensor.proto - Water quality pH measurement
├── load_cell.proto - Force measurement (gripper control)
└── pressure_sensor.proto - Pressure measurement (gripper control)
```
### Build Configuration
## Test References
### Test Suites
```
test/sensor_board/
├── test_gps_sensor/
├── test_imu_sensor/
├── test_load_sensor/
├── test_ph_sensor/
├── test_pressure_sensor/
└── test_sensor_basics/
```
### Running Tests
```bash
// Build all tests
pio test -e sensor_board
// Run with verbose output
pio test -e sensor_board -v
// Build only (no run)
pio test -e sensor_board --no-run
```
## Hardware References
### Microcontroller
- **STM32H753ZI** - ARM Cortex-M7, 480 MHz, 1 MB Flash
- **Datasheet**: ST Microelectronics STM32H7 reference
### Ethernet
- **LAN8742** - Ethernet PHY
- **Interface**: RMII (Reduced Media Independent Interface)
- **Link Speed**: 10/100 Mbps auto-negotiation
### Sensors
| Sensor
| Model
| Protocol
| Note
|
|---|
| GPS
| GY-NEO6MV2 (NEO-6M)
| UART 9600
| Default NMEA config
|
| IMU
| Reference design TBD
| I2C/SPI
| Dual IMU planned
|
| pH
| DFRobot SEN0161
| ADC Analog
| 40-sample averaging
|
| Load Cell
| Application specific
| ADC
| Dual cells (×2)
|
| Pressure
| Application specific
| ADC/I2C
| Dual sensors (×2)
|
## Development Workflow
### Building Firmware
```bash
// Build for sensor_board
pio run -e sensor_board
// Upload to board
pio run -e sensor_board --target upload
// Monitor serial output
pio device monitor -b 115200 -p COM4
```
### Development Cycle
```bash
// 1. Edit source code
// 2. Build
pio run -e sensor_board
// 3. Upload
pio run -e sensor_board --target upload
// 4. Monitor
pio device monitor
// 5. Run tests
pio test -e sensor_board
```
## Useful Commands
### PlatformIO CLI
```bash
// List available boards
pio boards
// Show board info
pio boards nucleo_h753zi
// Clean build
pio run -e sensor_board --target clean
// Full rebuild
pio run -e sensor_board --target clean --target upload
```
## Troubleshooting Guide
### Serial Monitor No Output
1. Check USB connection
2. Verify COM port in platformio.ini
3. Check baud rate (115200)
4. Verify UART initialization succeeded
### Sensor Shows IDLE
1. Check physical connection (UART/I2C/SPI)
2. Verify baud rate (for UART sensors)
3. Check pull-up resistors (for I2C)
4. Verify device address (for I2C/SPI)
### Network Packets Not Received
1. Check IP address configuration
2. Verify MAC address filtering
3. Check firewall settings
4. Verify UDP port 7 not blocked
### Low Heap Warning
1. Check for memory leaks in sensor drivers
2. Reduce buffer sizes
3. Verify UDP queue sizes
4. Check for recursive allocations
## Quick Reference Checklist
### Before Deployment
- [ ] All sensors connected and responding
- [ ] Network IP/MAC configured correctly
- [ ] Calibration parameters set for pH/load cells
- [ ] Serial monitor showing sensor data
- [ ] Heap usage monitored (>8KB free)
- [ ] UDP packets reaching destination
- [ ] Protobuf encoding verified
### Monitoring in Production
- [ ] Check sensor status codes
- [ ] Monitor heap usage trend
- [ ] Verify data ranges match expectations
- [ ] Track error rates per sensor
- [ ] Review network packet statistics
---
**Hope you had fun☮️**
**END OF DOCUMENTATION FOR SESOR BOARD**☮️
**Last Updated: April 14, 2026**
# Debugging Board
Lil gameboy doodad
# Overview
The debugging board is a **dedicated auxiliary system** whose only job is to make the rest of the robot less painful to work with.
It is not part of the rover’s core functionality.
## Purpose
At a high level, the debugging board serves roles:
### Visibility
Provide real-time insight into system state:
- logs
- status indicators
- network activity
- subsystem health
Instead of digging through serial output on multiple MCUs or adding temporary debug code everywhere, this board aggregates and presents useful information.
### Control / Interaction
Todo :D
### Isolation of debugging concerns
Todo :D
## Physical components
The exact hardware may evolve, but the debugging board generally consists of:
### Ethernet interface
- Connects to the system network (switch / internal bus)
- Receives and sends packets (including protobuf-based messages)
- Acts as a bridge between the debugging interface and the rest of the robot
### Display
- Shows system state, logs, or selected information
- It is a **ILI9341 SPI Display**
Used for quick, local feedback without needing a laptop.
### Input interface (buttons / panel)
- Physical buttons or switches
- Used to:
- trigger actions
- navigate menus
- send commands
# Display - ILI9341 Hardware Configuratoin
The debugging board incorporates a graphical display based on the ILI9341 controller. This display serves as the primary local interface for presenting system state, diagnostics, and user feedback.
The ILI9341 is a widely used TFT LCD controller that integrates display driving logic, internal GRAM (Graphics RAM), and a command-based interface over serial or parallel buses. In this system, it is used in **SPI mode**, which aligns with the board’s pin constraints and simplifies integration with the MCU.
## Functional Role in the System
Within the debugging board, the display is responsible for:
- Rendering system status (connectivity, subsystem health, etc.)
- Displaying structured debugging information
- Providing immediate visual feedback to user input (button interactions)
- Supporting simple UI constructs (menus, indicators, overlays)
The display is not intended for high-throughput graphics or complex rendering. Its role is **informational and interactive**, not graphical-intensive.
## Features of the ILI9341
The ILI9341 controller provides a set of features well suited for embedded applications.
### Resolution and Color Depth
- Resolution: **240 × 320 pixels**
- Color depth: **16-bit RGB (RGB565)**
This provides sufficient resolution for:
- text rendering
- simple UI layouts
- basic graphical elements (icons, shapes)
### Internal GRAM (Frame Buffer)
The controller includes internal **Graphics RAM (GRAM)**, which stores pixel data.
- The MCU does **not** need to maintain a full framebuffer
- Pixel data is written directly to the display over SPI
- The display retains the image until overwritten
This significantly reduces RAM requirements on the MCU, which is critical in embedded systems.
### Command-Based Interface
The display is controlled through a command/data protocol:
- Commands configure behavior (e.g., orientation, pixel format)
- Data writes update pixel values in GRAM
Typical operations include:
- setting an address window
- writing pixel data
- issuing initialization sequences
### Display Orientation and Addressing
The controller supports:
- configurable screen rotation (portrait / landscape)
- programmable address windows
This allows:
- flexible UI layout
- efficient partial updates (writing only specific regions)
### Hardware Reset and Initialization
The display requires:
- a hardware reset sequence
- a series of configuration commands during initialization
These typically configure:
- power control
- gamma curves
- pixel format
- memory access control
ILI9341 is a relatively complex and if you want to do anything with the internal library of it you need more than what can be written here. **Read the** [official documentation](https://cdn-shop.adafruit.com/datasheets/ILI9341.pdf)
## MCU Configuration
The SPI peripheral must be configured with:
- Mode: **Full-Duplex Master**
- Data size: **8-bit**
- First bit: **MSB-first**
- Clock polarity: **Low**
- Clock phase: **1st edge**
- NSS: **Software**
- Baud rate prescaler: selected based on display stability
These settings must match the display’s timing requirements.
For the baud rate, you want it to be as high as possible without it being unstable. For debugging and testing, it's good practice to lower it first, get it working there (as it is a lot more stable) and then increase it again.
# Display - ILI9341 Library
## Purpose
The `ili9341` library provides the low-level and mid-level drawing interface for the ILI9341-based display used on the debugging board.
Its role is to hide the raw command sequence and SPI transaction details of the display controller behind a set of functions for:
- initialization
- display configuration
- pixel and region drawing
- primitive graphics
- text rendering
- monochrome bitmap rendering
- rounded rectangle rendering
In other words, this library is the software layer that turns the display from a peripheral into a usable rendering surface.
## Scope of the Library
This library sits close to the hardware.
It is responsible for:
- driving the ILI9341 controller over SPI
- controlling the display GPIO lines (`CS`, `DC`, `RST`)
- issuing the controller initialization sequence
- writing pixel data to the display GRAM
- exposing simple drawing primitives for higher-level UI code
It is **not** responsible for:
- application UI logic
- layout management
- widget systems
- maintaining a full framebuffer
- asynchronous rendering scheduling
This is a direct-draw display driver and utility library, not a graphics framework.
## High-Level Design
The library is structured around four layers of functionality.
### Transport layer
These functions send commands and bytes over SPI:
- `ILI9341_SPI_Send()`
- `ILI9341_Write_Command()`
- `ILI9341_Write_Data()`
### Display control layer
These functions manage display state and configuration:
- `ILI9341_Reset()`
- `ILI9341_Set_Address()`
- `ILI9341_Set_Rotation()`
- `ILI9341_Enable()`
- `ILI9341_Init()`
### Primitive drawing layer
These functions draw directly to the screen:
- single colours
- pixels
- colour bursts
- lines
- rectangles
- bitmaps
- colour arrays
### Utility rendering layer
These functions build on the primitives to provide:
- text rendering
- rounded-corner rendering
- custom monochrome corner bitmap generation
This layered structure is important. Most higher-level code should use the drawing primitives and utility functions, not manually emit ILI9341 commands unless there is a very specific reason.
## Hardware Interface Definitions
The header defines the display connection through compile-time macros.
### SPI instance
```c
#define HSPI_INSTANCE &hspi1
```
This selects the SPI peripheral used to communicate with the display.
### GPIO control lines
```c
#define LCD_CS_PORT TFT_CS_GPIO_Port
#define LCD_CS_PIN TFT_CS_Pin
#define LCD_DC_PORT TFT_DC_GPIO_Port
#define LCD_DC_PIN TFT_DC_Pin
#define LCD_RST_PORT TFT_RESET_GPIO_Port
#define LCD_RST_PIN TFT_RESET_Pin
```
These define:
- chip select
- data/command selection
- hardware reset
The library assumes these symbols are provided by the board support layer.
### Screen dimensions
```c
#define ILI9341_SCREEN_HEIGHT 240
#define ILI9341_SCREEN_WIDTH 320
```
These define the nominal physical display dimensions..
### Burst limit
```c
#define BURST_MAX_SIZE 500
```
This controls the maximum temporary buffer size used during burst-style SPI transfers.
It affects:
- solid colour fills
- colour array streaming
- bitmap rendering
This is a performance and stack/RAM tradeoff parameter.
## Color Definitions
The header provides a set of named RGB565 color constants, for example:
- `BLACK`
- `WHITE`
- `RED`
- `GREEN`
- `BLUE`
- `YELLOW`
- `CYAN`
- `MAGENTA`
These are convenience values for application code and drawing functions.
All colors are represented in **16-bit RGB565 format**, which matches the configured pixel format of the display controller.
## Initialization Sequence
### `ILI9341_Init()`
```c
void ILI9341_Init(void);
```
This is the main initialization routine.
### What it does
It performs:
1. display enable
2. SPI init hook
3. hardware reset
4. software reset
5. a full controller configuration sequence
6. exit from sleep mode
7. display on
8. initial screen rotation selection
### Initialization sequence contents
The function writes a fixed command sequence configuring:
- power control
- driver timing
- pump ratio
- VCOM control
- memory access control
- pixel format
- frame rate
- gamma correction
- sleep exit
- display enable
This is the board’s current known-good configuration for the display.
### Why this matters
This sequence is not arbitrary boilerplate. It defines the electrical and visual behavior of the panel.
If it is modified, the maintainer must understand whether the change is:
- controller-required
- panel-specific
- timing-related
- cosmetic
- or cargo-culted from another project
## Basic Drawing Primitives
### `ILI9341_Draw_Colour()`
```c
void ILI9341_Draw_Colour(uint16_t Colour);
```
Writes one pixel’s worth of RGB565 data to the display.
This function assumes the correct address window is already set.
It is mainly an internal low-level helper.
### `ILI9341_Draw_Colour_Burst()`
```c
void ILI9341_Draw_Colour_Burst(uint16_t Colour, uint32_t Size);
```
Draws a repeated color value over a number of pixels.
#### Use case
Efficiently fill:
- large solid regions
- lines
- screen clears
#### How it works
It creates a temporary burst buffer containing repeated color bytes and transmits it in chunks.
This is much more efficient than sending each pixel individually.
#### Importance
This function is central to the performance of:
- full screen fills
- rectangle fills
- line drawing
### `ILI9341_Draw_Colour_Array()`
```c
void ILI9341_Draw_Colour_Array(const uint16_t *Colour, uint32_t PixelCount);
```
Draws an array of RGB565 pixel values.
#### Use case
Use this when the caller already has pixel data prepared, for example:
- image rendering
- precomputed graphics
- generated color buffers
#### Important implementation detail
The function converts each `uint16_t` color into big-endian byte order before sending.
This is correct for SPI transmission to the display controller.
### `ILI9341_Draw_Pixel()`
```c
void ILI9341_Draw_Pixel(uint16_t X, uint16_t Y, uint16_t Colour);
```
Draws one pixel at a specific coordinate.
#### Behavior
It:
- bounds checks the coordinate
- manually sets X address
- manually sets Y address
- issues memory write
- writes one pixel color
#### Performance note
This is a **very slow** operation compared to region-based drawing because it reissues addressing commands for every pixel.
It is suitable for:
- sparse pixel updates
- debugging
- very small shapes
It is not suitable for rendering larger regions.
### `ILI9341_Fill_Screen()`
```c
void ILI9341_Fill_Screen(uint16_t Colour);
```
Fills the whole display with one color.
#### Behavior
It sets the address window to the whole screen and then sends a repeated-color burst.
## Text Rendering
### `ILI9341_WriteString()`
```c
void ILI9341_WriteString(uint16_t x, uint16_t y, const char *str,
ILI9341_FontDef font, uint16_t color,
uint16_t bgcolor);
```
Renders a null-terminated string using the specified font and foreground/background colors.
### Behavior
- iterates through each character
- wraps to the next line if the current X position exceeds screen width
- stops if the next line would exceed screen height
### Internal helper
This uses the internal function:
```c
static void ILI9341_WriteChar(...)
```
which renders one character pixel-by-pixel using the font bitmap.
## Bitmap Rendering
### `ILI9341_Draw_Bitmap()`
```c
void ILI9341_Draw_Bitmap(uint16_t x, uint16_t y,
uint16_t w, uint16_t h,
const uint8_t *bitmap,
uint16_t Color, uint16_t BgColor);
```
Draws a **1-bit-per-pixel bitmap** into a rectangular region.
### Expected bitmap format
The input bitmap is interpreted as packed monochrome data:
- 1 bit per pixel
- row-major
- MSB-first within each byte
### Rendering behavior
For each bit:
- set bit -> draw `Color`
- clear bit -> draw `BgColor`
### Use case
This is useful for:
- icons
- glyph-like shapes
- masks
- rounded corner patterns
It is not for full-color image rendering.
## R³: Rounded Rectangle Rendering
The library includes support for rounded rectangle outlines using generated monochrome corner bitmaps.
This is more advanced than the rest of the primitive API and deserves separate explanation.
### Why?
The reasons why the R³ system is highly important - if not necessary - are plenty and extensive. That's why I compiled a pastebin[ that includes all reasons](https://pastebin.com/h6b2e2W0). Feel free to read it even though I believe it is pretty self explanatory
### Concept
A rounded rectangle is rendered by:
1. generating a 1bpp bitmap for one rounded corner
2. rotating that bitmap to obtain all four corners
3. drawing the four corner bitmaps
4. drawing straight rectangle segments between them
This is a practical method for an SPI-driven display because it avoids expensive per-pixel circle calculations at draw time for every corner.
### Internal helpers
The implementation includes internal static helpers:
- `ILI9341_Get_Rounded_Corner_Bitmap()`
- `bitmap_rotate_90_cw_1bpp()`
- `ILI9341_Build_All_Rounded_Corners()`
- `ILI9341_Draw_Rectangle_Custom_Corner()`
These are not part of the public API, but they are important for maintainers to understand.
### `ILI9341_Draw_Rectangle_Rounded_Corner()`
```c
result_t ILI9341_Draw_Rectangle_Rounded_Corner(
uint16_t X, uint16_t Y, uint16_t Width, uint16_t Height,
uint8_t thickness, uint8_t radius,
uint8_t *corner_buffer, size_t corner_buffer_size,
uint16_t Colour, uint16_t Bg_Colour);
```
This is the main public rounded rectangle API currently implemented with explicit caller-provided corner buffer storage.
#### Why caller-provided memory is used
The function requires the caller to provide a temporary buffer for the generated corner bitmaps.
This avoids hidden dynamic allocation and gives the caller control over memory use.
#### Buffer sizing
The function expects enough memory for **four** 1bpp bitmaps, one for each corner.
It computes the required size as:
```c
4 * (((radius + 7) >> 3) * radius)
```
in bytes.
#### Return values
- `RESULT_OK` on success
- `RESULT_ERR_NO_MEM` if the provided buffer is too small
- `RESULT_ERR_INVALID_ARG` for invalid parameters via internal helpers
#### Use case
This function is appropriate when the UI wants rounded bordered rectangles without a full framebuffer.
# Menu Driver - Overview
## Purpose
The menu driver is a **page-based UI framework** for an embedded display (ILI9341).
It defines:
- how UI is structured into pages
- how state is stored per page
- how navigation works
- how rendering is organized
## Architecture Position
```
[ Application Logic ]
↓[ Menu Driver ]
↓[ ILI9341 Driver ]
↓[ SPI / Hardware ]
```
It **does not**:
- own the main loop
- schedule tasks
- interpret input fully
It **does**:
- define UI structure
- manage page lifecycle
- coordinate rendering
---
## 1.3 Design Model
Everything revolves around:
> “A UI is a collection of pages with lifecycle and state.”
Each page has:
- state
- init/update/render/destruct
- parent relationship
```
Input / System Events
│
▼
┌─────────────────────┐
│ menu_manager_t │
│─────────────────────│
│ active_page_id │
│ pages[] │
│ get_input() │
└─────────┬───────────┘
│ selects active page
▼
┌──────────────────────────────────┐
│ Active Page │
│──────────────────────────────────│
│ state pointer │
│ init() ─┐ │
│ update() ├─ custom page │
│ render() ┤ behavior │
│ destruct() ┘ │
└────────────────┬─────────────────┘
│ reads/writes
▼
┌──────────────────┐
│ Page State │
│──────────────────│
│ selection │
│ cached values │
│ render flags │
│ page-local data │
└──────────────────┘
```
# Menu Driver - Configuration Layer
## Visual Configuration
```c
#define MENU_DRIVER_BACKGROUND_COLOR 0x0000
#define MENU_DRIVER_FOREGROUND_COLOR 0xFFFF
```
Black background, white foreground.
## Layout Constraints
```c
#define MENU_SIDEBAR_WIDTH 38
```
Sidebar (ribbon) width.
## Capacity Limits
### List Pages
```c
#define MAX_LIST_ENTRIES 10
#define MAX_LIST_TITLE_LEN 24
```
### Overview Pages
```c
#define MENU_OVERVIEW_MAX_ENTRIES 10
#define MENU_OVERVIEW_MAX_ENTRY_TITLE_LEN 12
```
### Global
```c
#define MAX_PAGE_NAME_LEN 20
```
These define:
- memory footprint
- UI density
- rendering assumptions
# Menu Driver - Core Data Structures
## Page State Types
A **page state** is:
> The **persistent data container** that represents everything a UI page needs to function between frames.
Not just data. It’s:
- memory of what the user did
- memory of what was rendered
- memory of external data (diagnostics, etc.)
### List Page State
```c
typedef struct {
uint8_t num_entries;
uint8_t selected_index;
uint8_t entry_ids[MAX_LIST_ENTRIES];
const uint8_t (*entry_icons)[MENU_DRIVER_ICON_BYTE_SIZE];
bool first_render;
} page_list_state;
```
#### Responsibilities:
- track selection
- map entries → page IDs
- hold icons
- manage first render optimization
### Overview Page State
Todo :D
### State Union
```c
typedef union {
page_list_state list;
page_overview_state overview;
} menu_page_state;
```
### Page Type
```c
typedef enum {
MENU_PAGE_TYPE_LIST,
MENU_PAGE_TYPE_OVERVIEW,
} menu_page_type_t;
```
Used to interpret the union correctly.
## Page Object
```c
typedef struct {
menu_page_state *state;
menu_page_type_t type;
unsigned char id;
unsigned char parent_id;
bool needs_render;
char name[MAX_PAGE_NAME_LEN];
void (*init)(menu_page_state *);
void (*update)(menu_manager_t *);
void (*render)(menu_manager_t *);
void (*destruct)(menu_page_state *);
} menu_page_t;
```
This is the **core abstraction**.
### Definition and Role
A page object represents one logical screen within the menu system. It encapsulates:
- the data required to represent the page (via its state)
- the functions required to manage its lifecycle
- metadata used for navigation and identification
This abstraction allows the menu system to treat all pages uniformly, regardless of their internal implementation or purpose.
### Important Fields
#### Render Control
```c
bool needs_render;
```
This flag indicates whether the page requires re-rendering.
It allows the system to avoid unnecessary redraw operations, which is critical in environments where display updates are expensive.
The responsibility for managing this flag lies with the **page implementation**.
### Lifecycle Function Pointers
Each page defines its own behavior through four function pointers:
#### Initialization
```c
void (*init)(menu_page_state *state);
```
Responsible for preparing the page state when the page becomes active.
Typical responsibilities include:
- resetting selection indices
- initializing flags
- preparing any required data structures
#### Update
```c
void (*update)(struct menu_manager_t *manager);
```
Handles input processing and state updates.
This function is expected to:
- read input through the manager
- modify internal state accordingly
- trigger page transitions if necessary
#### Render
```c
void (*render)(struct menu_manager_t *manager);
```
Responsible for drawing the page to the display.
This function should:
- read from the page state
- issue drawing commands via the display driver
- respect the `needs_render` flag when applicable
#### Destruction
```c
void (*destruct)(menu_page_state *state);
```
Handles cleanup when the page is no longer active.
In embedded systems, this typically involves:
- resetting state fields
- releasing logical ownership of resources
Dynamic memory cleanup is generally not required unless explicitly used.
## Menu Manager
```c
typedef struct {
unsigned char active_page_id;
const menu_page_t *pages;
menu_input (*get_input)(void);
} menu_manager_t;
```
Responsibilities:
- track active page
- provide input access
- hold page table
Does NOT:
- validate anything
- own memory
- manage concurrency
# Menu Driver - Overview Page
## Introduction
The **List Page** is a navigation-oriented page type within the menu driver. It provides a structured interface for selecting between multiple entries, typically representing:
- subpages
- actions
- system modules
It is the primary mechanism for **user-driven navigation** within the menu system.
## Purpose
The list page exists to answer:
> **“Where do you want to go next?”**
It is not responsible for displaying system state in detail. Instead, it:
- presents a bounded set of selectable entries
- tracks the current selection
- provides visual feedback for navigation
- enables transitions to other pages
In practice, it functions as the **entry point and routing layer** of the UI.
## Architectural Role
The list page sits at the intersection of:
- **input handling** (user navigation)
- **menu structure** (page hierarchy)
- **visual rendering** (icons and labels)
```
[ Input ] → [ List Page ] → [ Page Transition ]
```
It does not consume system data (like overview pages), but rather controls **flow through the interface**.
## Data Model
The list page is backed by the following state structure:
```c
typedef struct {
uint8_t num_entries;
uint8_t selected_index;
uint8_t entry_ids[MAX_LIST_ENTRIES];
const uint8_t (*entry_icons)[MENU_DRIVER_ICON_BYTE_SIZE];
bool first_render;
} page_list_state;
```
### Entry Management
`num_entries`
Defines how many entries are currently active.
This value must not exceed `MAX_LIST_ENTRIES`.
`entry_ids`
Maps each visible entry to a logical identifier.
These IDs are typically used to:
- determine which page to switch to
- associate actions with selections
`entry_icons`
Pointer to icon data associated with each entry.
- Icons are rendered alongside entries
- Each icon is a fixed-size bitmap
- Icons are stored in flash as static data
### Selection State
#### `selected_index`
Indicates which entry is currently selected.
This is the central piece of state for navigation.
All rendering and transitions depend on this value.
### Render Control
`first_render`
Indicates whether the page is being rendered for the first time.
Used to:
- trigger full initial draw
- avoid redundant rendering of static UI elements
## Rendering Model
The list page uses a **focused rendering strategy**, rather than displaying all entries simultaneously.
### Visible Entries
Only three entries are rendered at any time:
- previous entry
- current (selected) entry
- next entry
This creates a scrolling effect without requiring full list rendering.
### Rendering Optimization
The only expensive draw of the list page is the initial one which draws the selection border, all initial entries (both icons and names).
After that the only thing that gets redrawn are the icons and the texts. There is also heavier optimization done for minimal font redrawing by keeping track of previously rendered text widths.
This is critical for SPI-driven displays, where bandwidth is limited.
## Interaction Model
The list page assumes an abstract input interface:
```
menu_input (*get_input)(void);
```
The page does not interpret physical inputs directly. Instead, it operates on abstract input values, allowing it to remain independent of hardware specifics.
Expected interactions include:
- move selection up
- move selection down
- confirm selection
## Relationship to Menu System
The list page enables hierarchical navigation through:
- `entry_ids` → target page identifiers
- `parent_id` (in `menu_page_t`) → upward navigation
This allows the menu system to behave as a **tree of pages**, rather than a flat structure.
## Performance Considerations
The list page is designed for constrained environments:
- partial rendering minimizes SPI usage
- static memory avoids allocation overhead
- limited visible entries reduce draw complexity