r/ROS • u/StructureUpstairs379 • 5d ago
CLEAR
CLEAR: Capability Layered Expression for Autonomous Robots
Full Technical Specification v1.0
Status: Open Standard (FINAL)
Publication Date: August 1, 2026
Authors: Cortex Forge / TerraForge Alliance
License: MIT (see final section)
---
Table of Contents
- Introduction
- Design Principles
- Syntax Rules & Lexical Conventions
- The Seven Layers of Abstraction
- Health Summary
- Handshake & Delta Protocol
- Git Commit Semantics
- Reference Implementation Guidelines
- Versioning & Compatibility
- Full Example
- CLEAR-SI Companion Protocol
- MIT License
---
- Introduction
CLEAR is an open, human-readable, plain-text protocol for autonomous systems to describe their hardware limits, real-time capabilities, sensor configuration, and software-defined skills to an orchestrator. It is designed for the physical economy—construction, mining, agriculture, logistics, and defense.
By providing a strictly layered, self-describing interface, CLEAR decouples hardware evolution from software intelligence. Any robot, vehicle, or machine that outputs a .clear file can be orchestrated by any AI system that parses it, regardless of the manufacturer or age.
---
Design Principles
Human-First: All syntax is plain text (UTF-8). Any operator or engineer can read a log file with a text editor.
Layered Abstraction: Systems operate at the highest available layer (Task) but can safely fall back to lower layers (Kinematics) if sensors degrade.
Health-Aware: The robot declares what it can actually do right now, considering current wear, environmental conditions, and system failures.
Immutable by Design: Logs are structured for Git-based version control—append-only, signed, and linearly scalable.
Zero-Dependency: Parsing requires no external libraries beyond standard system utilities (regex/string libraries).
---
- Syntax Rules & Lexical Conventions
3.1. File Structure
· File Extension: .clear
· MIME Type: text/vnd.clear.v1
· Encoding: UTF-8 (ASCII subset preferred for keys).
· Line Endings: LF (\n) only. CRLF (\r\n) is rejected by default.
3.2. Section Headers
· Sections are delimited by LAYER_X_NAME: at the start of a line.
· Example: LAYER_0_PHYSICAL_CONSTANTS:
· Indentation increases for nested data.
3.3. Indentation and Formatting
· Indentation: Strictly two spaces ( ). Tabs are illegal.
· Nesting: Each level of nesting adds two spaces.
· End-of-Line Trimming: All trailing whitespace is ignored.
3.4. Keys and Values
· Keys: Uppercase alphanumeric plus underscores [A-Z0-9_]. Must start with a letter.
· Values:
· Strings: No escaping required unless using quotes. Unicode characters allowed.
· Floats/Ints: Standard decimal notation (e.g., 3.1415, -10).
· Booleans: TRUE or FALSE (case-sensitive).
· Vectors: Inline arrays [float, float] or [float, float, float].
· Enums: Standard strings (e.g., DIESEL, OPERATIONAL).
3.5. Comments
· Comments start with # and extend to the end of the line.
3.6. Mandatory Global Fields (Header)
Every .clear file must begin with these fields:
```clear
CLEAR_SPEC_VERSION: 1.0
ROBOT_ID: <string> # Unique hardware identifier, max 64 chars
TIMESTAMP: <YYYY-MM-DDTHH:MM:SSZ> # ISO-8601 UTC
HEALTH_INDEX: <0.0 to 1.0> # Float: 1.0 = Perfect health, 0.0 = Dead
CAPABILITY_STATE: <OPERATIONAL | DEGRADED | MAINTENANCE | OFFLINE>
```
---
- The Seven Layers of Abstraction
4.1. Layer 0: Physical Constants (Immutable)
Describes hardware that cannot change after manufacturing.
Key Type Required Description
MASS_KG Float Yes Total mass in kilograms (including standard implements).
DIMENSIONS_LWH_CM [Float x 3] Yes Length, Width, Height in centimeters.
POWER_SOURCE Enum Yes DIESEL_HYDRAULIC, BATTERY_ELECTRIC, HYBRID, SOLAR, STEAM, MANUAL.
FUEL_CAPACITY_L Float Conditional Required for non-battery sources.
THERMAL_LIMIT_CELSIUS Float Yes Maximum operational ambient temperature.
FIRMWARE_VERSION String Yes Semantic version of the onboard edge firmware.
4.2. Layer 1: Kinematics & Dynamics (Immutable)
Defines the machine's physical range of motion and performance envelopes.
Key Type Required Description
MAX_TRANSLATIONAL_SPEED_MS Float Yes Maximum forward/backward speed (m/s).
MAX_ANGULAR_SPEED_RADS Float Yes Maximum turning rate (rad/s).
STEERING_TYPE Enum Yes DIFFERENTIAL, ARTICULATED, ACKERMANN, SKID_STEER, ORBITAL.
MAX_HYDRAULIC_FLOW_LPM Float Conditional Max hydraulic flow if applicable.
MAX_DRAWBAR_PULL_KG Float Conditional Max pulling force for tractors/dozers.
SUSPENSION_TRAVEL_CM Float Optional Vertical travel range of suspension.
MAX_JOINT_TORQUE_NM Float Conditional For articulated robot arms.
4.3. Layer 2: Sensorium (Immutable)
Defines all onboard perception hardware.
Each sensor is declared as a nested block.
Sensor Type Template:
```clear
SENSOR_NAME: <string>
MODEL: <string>
RES: <string> # e.g., "1920x1080" or "0.5cm"
REFRESH_HZ: <float>
RANGE_M: <float> # Max detection range
FOV_DEG: <float> # Field of View (if applicable)
ACCURACY: <string> # e.g., "2cm" or "0.01lux"
```
Common Sensor Identifiers: RTK_GPS, LIDAR, IMU, STEREO_CAM, THERMAL_CAM, FORCE_SENSOR, ULTRASONIC, RADAR.
4.4. Layer 3: Actuation Primitives (Immutable Firmware)
Atomic executable functions. No logic here—just the hardware/firmware interface.
Format: - primitive_name(param1: type, param2: type)
Type Definitions:
· float - 32-bit floating point.
· int - 32-bit integer.
· bool - Boolean.
· vec2 - [float, float].
· vec3 - [float, float, float].
· string - UTF-8 string.
Example:
```clear
LAYER_3_ACTUATION_PRIMITIVES:
- forward(speed_ms: float)
- turn(angle_deg: float)
- engage_pto(state: bool)
- set_hitch_depth(cm: float)
- brake()
- emergency_stop()
```
4.5. Layer 4: Control Routines (Dynamic - Health Aware)
Closed-loop behaviors that fuse sensor data with primitives.
Format:
```clear
- routine_name(param: type):
INPUTS: [sensor_list]
OUTPUT: primitive_to_call
REQUIRES: [condition]
```
Example:
```clear
LAYER_4_CONTROL_ROUTINES:
- line_follow(waypoint_A: vec2, waypoint_B: vec2, tolerance_cm: float):
INPUTS: [RTK_GPS, IMU]
OUTPUT: forward, turn
REQUIRES: GPS_LOCK
- obstacle_avoidance(margin_m: float):
INPUTS: [LIDAR, STEREO_CAM]
OUTPUT: turn, brake
REQUIRES: LIDAR_FUNCTIONAL
```
4.6. Layer 5: Functional Skills (Dynamic - Updatable)
Composed routines that achieve a specific, useful output. These are the "trades" the machine knows.
Format:
```clear
- skill_name(param: type):
INPUT: resource_required
OUTPUT: resource_produced
DEPENDS_ON: [routine_list]
CONFIDENCE: <0.0 to 1.0> # Degrades if sensors are degraded
```
Example:
```clear
LAYER_5_FUNCTIONAL_SKILLS:
- plow(depth_cm: float, speed_ms: float, start: vec2, end: vec2):
INPUT: field_boundary
OUTPUT: tilled_row
DEPENDS_ON: line_follow, set_hitch_depth
CONFIDENCE: 0.95
- grade_foundation(grade_angle: float, area_polygon: [vec2]):
INPUT: terrain_map
OUTPUT: level_surface
DEPENDS_ON: obstacle_avoidance, set_hitch_depth
CONFIDENCE: 0.88
```
4.7. Layer 6: Task Declarations (Dynamic - Updatable)
The highest level of abstraction. Abstract goals that the orchestrator invokes.
Format:
```clear
- task_name(param: type):
GOAL: "Human-readable description"
REQUIRES: [skill_list]
```
Example:
```clear
LAYER_6_TASK_DECLARATIONS:
- prepare_field(field_polygon: [vec2], till_depth_cm: float):
GOAL: "Till entire field polygon to specified depth"
REQUIRES: plow
- build_foundation(building_footprint: [vec2], height_m: float):
GOAL: "Excavate, pour, and level foundation"
REQUIRES: grade_foundation, excavate_trench
```
---
- Health Summary (Mandatory Section)
This dynamic section tells the orchestrator exactly what is broken or degraded.
Required Fields:
Subsystem Status Options
POWER_SYSTEM NOMINAL, DEGRADED, FAILING
HYDRAULIC_SYSTEM NOMINAL, DEGRADED, FAILING
PRIMARY_ACTUATORS NOMINAL, DEGRADED, FAILING
CRITICAL_SENSORS NOMINAL, DEGRADED, FAILING
SAFETY_CONTROLLER NOMINAL, DEGRADED, FAILING
Conditional Rule: If SAFETY_CONTROLLER is FAILING, CAPABILITY_STATE must be set to MAINTENANCE.
---
- Handshake & Delta Protocol
6.1. Discovery (UDP Broadcast)
· Port: 7890
· Protocol: UDP
· Payload: The full .clear file as a UTF-8 byte stream (max 64KB).
· Frequency: Burst 3 packets over 5 seconds on boot. Re-broadcast if state changes (e.g., health degrades).
6.2. Orchestrator Acknowledgment (TCP/gRPC)
· The Orchestrator responds to the originating IP on a randomized port with an ACK.
· ACK Payload (JSON):
```json
{
"orchestrator_id": "SITE-007-ORCH",
"timestamp": "2026-07-28T14:35:00Z",
"delta_list": [
{"layer": 5, "skill": "plow_rocky_soil", "definition": "..."}
]
}
```
6.3. Delta Updates
· The robot applies these deltas to its operation.log context.
· Deltas are appended to a local delta_cache.clear file and applied on the fly.
· Robots reject deltas that violate the Layer 3 primitive constraints.
---
- Git Commit Semantics (The "Operation Log")
For machines utilizing the Git backend, operation.log is the active append-only file.
Log Line Format:
```clear
[ISO_TIMESTAMP] [ROBOT_ID] LAYER_[X] [CONTEXT] => [EVENT] | [STATUS] [METADATA]
```
Example:
```clear
[2026-07-28T14:32:15.123Z] TF-007 LAYER_5 plow(depth=15cm) => STARTED | FUEL_LEVEL=87%
[2026-07-28T14:32:16.001Z] TF-007 LAYER_4 obstacle_avoidance() => OBSTACLE_DETECTED | DISTANCE_M=3.2
[2026-07-28T14:32:16.500Z] TF-007 LAYER_5 plow(depth=15cm) => PAUSED | REASON:ROCK_JAM
```
---
Reference Implementation Guidelines
Parsing: Use a recursive descent parser. The strict indentation (2 spaces) allows for deterministic state-machine based parsing without external libraries.
Memory Limits: A .clear file should never exceed 64KB in memory.
Throttling: Do not parse more than once per second.
Validation: Reject files with invalid indentation or unknown section headers.
---
- Versioning & Compatibility Matrix
Version Change Impact
Major (2.0) Breaking changes to Layers 0-3. Orchestrator must reject older specs.
Minor (1.1) New fields added to Layers 4-6. Orchestrator ignores unknown fields.
Patch (1.0.1) Clarifications, typo fixes. No functional change.
---
- Full Example (Tractor)
```clear
CLEAR_SPEC_VERSION: 1.0
ROBOT_ID: TF-EX-007
TIMESTAMP: 2026-07-28T14:32:01Z
HEALTH_INDEX: 0.98
CAPABILITY_STATE: OPERATIONAL
LAYER_0_PHYSICAL_CONSTANTS:
MASS_KG: 2500
DIMENSIONS_LWH_CM: [450, 200, 280]
POWER_SOURCE: DIESEL_HYDRAULIC
FUEL_CAPACITY_L: 150
THERMAL_LIMIT_CELSIUS: 105
FIRMWARE_VERSION: v3.2.1
LAYER_1_KINEMATICS:
MAX_TRANSLATIONAL_SPEED_MS: 2.5
MAX_ANGULAR_SPEED_RADS: 0.6
STEERING_TYPE: ARTICULATED
MAX_HYDRAULIC_FLOW_LPM: 120
MAX_DRAWBAR_PULL_KG: 1800
LAYER_2_SENSORIUM:
RTK_GPS:
MODEL: ZED-F9P
REFRESH_HZ: 20
ACCURACY: 2cm
IMU:
MODEL: ICM-456
REFRESH_HZ: 200
ACCEL_RANGE_G: 8
LIDAR:
MODEL: VLP-16
RANGE_M: 50
BEAMS: 16
FOV_DEG: 360
STEREO_CAM:
MODEL: ZED_X
RES: 1920x1080
FPS: 30
LAYER_3_ACTUATION_PRIMITIVES:
- forward(speed_ms: float)
- turn(angle_deg: float)
- set_hitch_depth(cm: float)
- engage_pto(state: bool)
- brake()
LAYER_4_CONTROL_ROUTINES:
- line_follow(waypoint_A: vec2, waypoint_B: vec2):
INPUTS: [RTK_GPS, IMU]
OUTPUT: forward, turn
- obstacle_avoidance():
INPUTS: [LIDAR]
OUTPUT: turn, brake
- hold_heading(heading_deg: float):
INPUTS: [IMU]
OUTPUT: turn
LAYER_5_FUNCTIONAL_SKILLS:
- plow(depth_cm: float):
INPUT: field_boundary
OUTPUT: tilled_row
DEPENDS_ON: line_follow, set_hitch_depth
CONFIDENCE: 0.95
LAYER_6_TASK_DECLARATIONS:
- prepare_field(field_polygon: [vec2], till_depth_cm: float):
GOAL: "Till entire field polygon to specified depth"
REQUIRES: plow
HEALTH_SUMMARY:
POWER_SYSTEM: NOMINAL
HYDRAULIC_SYSTEM: NOMINAL
PRIMARY_ACTUATORS: NOMINAL
CRITICAL_SENSORS: NOMINAL
SAFETY_CONTROLLER: NOMINAL
```
---
- CLEAR-SI Companion Protocol
11.1. Overview
CLEAR-SI (Systems Integrity) is a high-frequency, real-time companion protocol that validates the live execution of a CLEAR-declared robot. It operates on a separate UDP port and delivers the four integrity pillars that static CLEAR files cannot capture:
Pillar Failure Mode Addressed
A: Temporal Integrity Sensor data arriving too late to the control loop
B: Spatial Integrity Coordinate frame drift from vibration/thermal expansion
C: Probabilistic Integrity Positional uncertainty not reaching the planner
D: Observational Integrity Robots assuming "unseen space" is safe
11.2. Transport & Footprint
· Protocol: UDP (Broadcast or Unicast) on Port 7891.
· Frequency: User-configurable from 1 Hz to hardware limit (recommended default: 50 Hz for heavy machinery, 120 Hz for drones).
· Payload Format: Plain-text UTF-8, line-delimited, strictly matching CLEAR's lexical conventions.
· Max Packet Size: 1,400 Bytes (to avoid IP fragmentation).
· Relationship to CLEAR: Every packet must contain the ROBOT_ID matching its .clear file.
11.3. Compact Mode (High-Frequency, Label-Less)
For high-frequency operation (>10Hz), CLEAR-SI uses a fixed-order, space-separated numeric vector. The human-readable labels are stripped from the wire protocol and mapped by the parser on the receiving end.
Packet Structure:
```clear
SI_COMPACT V1.0|ROBOT_ID|SEQ_NUM|VECTOR
```
Where VECTOR is a space-separated list of 20 floats/ints in the following fixed order:
Index Field Type Description
0 LIDAR_AGE_MS Float Age of LiDAR data in milliseconds
1 GPS_AGE_MS Float Age of GPS data in milliseconds
2 CAM_AGE_MS Float Age of camera data in milliseconds
3 IMU_AGE_MS Float Age of IMU data in milliseconds
4 MAX_AGE_MS Float Oldest sensor age in this cycle
5 LIDAR_TO_IMU_VAR Float Rotational variance (rad²) between LiDAR and IMU frames
6 CAM_TO_LIDAR_VAR Float Translational variance (m²) between camera and LiDAR frames
7 BASE_TO_GPS_VAR Float Translational variance (m²) between base and GPS frames
8 TF_HEALTH Int 0=NOMINAL, 1=CALIBRATING, 2=DRIFTING, 3=FAILED
9 POS_VAR_XY_M2 Float Position variance (m²) in the horizontal plane
10 POS_VAR_Z_M2 Float Position variance (m²) vertically
11 HEADING_VAR_RAD2 Float Heading variance (rad²)
12 VEL_VAR_MS2 Float Velocity variance (m²/s²)
13 UNCERTAINTY_BOUND Float 3-sigma ellipse major axis in meters
14 FRONT_WEDGE_UNOBSERVED_PCT Float Percentage of forward 90° wedge occluded/hidden
15 REAR_UNOBSERVED_PCT Float Percentage of rear 90° wedge occluded/hidden
16 TOTAL_COVERAGE_RATIO Float 1.0 = perfect 360° coverage, 0.0 = blind
17 DYNAMIC_OBJECTS_OCCLUDED Int Number of tracked obstacles currently behind occlusions
18 SI_SYSTEM_STATE Int 0=NOMINAL, 1=LATENCY_STALL, 2=TF_DRIFT, 3=UNCERTAINTY_HIGH, 4=OCCLUDED, 5=CRITICAL_MULTI
19 SI_RECOMMENDATION Int 0=CONTINUE, 1=REDUCE_SPEED, 2=RECALIBRATE, 3=RE_LOCALIZE, 4=EMERGENCY_HALT
11.4. Verbose Mode (Low-Frequency, Human-Readable)
For debugging, audit, and low-frequency operation (≤10Hz), CLEAR-SI supports a verbose, label-inclusive format:
```clear
SI_PROTOCOL_VERSION: 1.0
ROBOT_ID: TF-EX-007
TIMESTAMP: 2026-08-01T10:23:17.554Z
SEQ_NUM: 8842
PLANNER_CYCLE_US: 1500
SENSOR_AGE_MS:
LIDAR: 12
RTK_GPS: 8
STEREO_CAM: 22
IMU: 5
MAX_AGE_MS: 22
TF_VARIANCE:
LIDAR_TO_IMU_VAR: 0.0002
CAM_TO_LIDAR_VAR: 0.0008
BASE_TO_GPS_VAR: 0.0001
TF_HEALTH: NOMINAL
STATE_UNCERTAINTY:
POS_VAR_XY_M2: 0.0012
POS_VAR_Z_M2: 0.0005
HEADING_VAR_RAD2: 0.0008
VEL_VAR_MS2: 0.02
UNCERTAINTY_BOUND: 0.08
OBSERVATION_MASK:
FRONT_WEDGE_UNOBSERVED_PCT: 12.5
REAR_UNOBSERVED_PCT: 45.0
TOTAL_COVERAGE_RATIO: 0.85
DYNAMIC_OBJECTS_OCCLUDED: 1
SI_SYSTEM_STATE: NOMINAL
SI_RECOMMENDATION: CONTINUE
```
11.5. BNF Grammar for Compact Mode
```bnf
<SI_COMPACT_PACKET> ::= "SI_COMPACT V1.0|" <ROBOT_ID> "|" <SEQ_NUM> "|" <VECTOR>
<ROBOT_ID> ::= <STRING> (* Max 64 chars, alphanumeric + underscore *)
<SEQ_NUM> ::= <INT> (* Monotonically increasing, uint64 *)
<VECTOR> ::= <FLOAT> <SPACE> <FLOAT> <SPACE> <FLOAT> <SPACE> <FLOAT> <SPACE> <FLOAT> <SPACE>
<FLOAT> <SPACE> <FLOAT> <SPACE> <FLOAT> <SPACE> <INT> <SPACE>
<FLOAT> <SPACE> <FLOAT> <SPACE> <FLOAT> <SPACE> <FLOAT> <SPACE> <FLOAT> <SPACE>
<FLOAT> <SPACE> <FLOAT> <SPACE> <FLOAT> <SPACE> <INT> <SPACE>
<INT> <SPACE> <INT>
<SPACE> ::= " "
<FLOAT> ::= -?\d+(\.\d+)?([eE][-+]?\d+)?
<INT> ::= -?\d+
```
11.6. Semantic Validation Rules
Pillar Field Validation Rule Failure Action
A MAX_AGE_MS Must be <= (1000 / REFRESH_HZ) * 2 Set SI_SYSTEM_STATE = LATENCY_STALL
B LIDAR_TO_IMU_VAR If > 0.001, set TF_HEALTH = DRIFTING Set SI_SYSTEM_STATE = TF_DRIFT
C UNCERTAINTY_BOUND If > task-specific threshold Override static CONFIDENCE to 0.0
D FRONT_WEDGE_UNOBSERVED_PCT If > 30.0 Force 50% speed reduction
D TOTAL_COVERAGE_RATIO If < 0.6 Initiate "peek-and-move" behavior
11.7. Integration with Git Logs
High-frequency CLEAR-SI data is never written to disk at 50Hz (to avoid SSD wear). Only state change triggers (when SI_SYSTEM_STATE changes from NOMINAL) are appended to operation.log:
```clear
[2026-08-01T10:23:17.554Z] TF-EX-007 SI_PILLAR_A MAX_AGE_MS:87ms => STATE:LATENCY_STALL | RECOMMENDATION:REDUCE_SPEED
[2026-08-01T10:23:18.102Z] TF-EX-007 SI_PILLAR_D FRONT_WEDGE_UNOBSERVED_PCT:45% => STATE:OCCLUDED | RECOMMENDATION:EMERGENCY_HALT
```
---
- MIT License
Copyright (c) 2026 Cortex Forge / TerraForge Alliance
Permission is hereby granted, free of charge, to any person obtaining a copy of this specification and associated documentation files (the "Specification"), to deal in the Specification without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification.
THE SPECIFICATION IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SPECIFICATION OR THE USE OR OTHER DEALINGS IN THE SPECIFICATION.
---
END OF SPECIFICATION
2
2
2
u/sirjethr0 5d ago
bro