Sync inav to Gitea

docs/javascript_programming/api_definitions_summary.md

@@ -0,0 +1,284 @@
+# INAV API Definitions - Complete Implementation
+
+## Overview
+
+The INAV JavaScript API definitions are implemented in `js/transpiler/api/definitions/`. These files define the complete JavaScript API surface that maps to INAV firmware logic conditions.
+
+## API Definition Files
+
+### 1. ✅ **flight.js** - Flight Telemetry (READ-ONLY)
+**Source**: `src/main/programming/logic_condition.c` (OPERAND_FLIGHT)
+
+Contains ~40 flight parameters including:
+- **Timing**: armTimer, flightTime
+- **Distance**: homeDistance, tripDistance, homeDirection
+- **Communication**: rssi
+- **Battery**: vbat, cellVoltage, current, mahDrawn, mwhDrawn, batteryPercentage
+- **GPS**: gpsSats, gpsValid
+- **Speed/Altitude**: groundSpeed, altitude, verticalSpeed
+- **Attitude**: roll, pitch, yaw, heading, throttlePos
+- **State**: isArmed, isAutoLaunch, isFailsafe
+- **Profile**: mixerProfile
+- **Navigation**: activeWpNumber, activeWpAction, courseToHome, gpsCourseOverGround
+- **Modes** (nested): failsafe, manual, rth, poshold, althold, wp, gcs_nav, airmode, angle, horizon, cruise
+
+### 2. ✅ **override.js** - Flight Control Overrides (WRITABLE)
+**Source**: `src/main/programming/logic_condition.c` (OPERATION_OVERRIDE_*)
+
+Contains override operations:
+- **Throttle**: throttleScale, throttle
+- **VTX** (nested): power, band, channel
+- **Attitude** (nested): roll.angle, roll.rate, pitch.angle, pitch.rate, yaw.angle, yaw.rate
+- **Heading**: heading override
+- **RC Channels**: rcChannel[] array
+- **Arming**: armSafety
+- **OSD**: osdElement
+
+### 3. ✅ **rc.js** - RC Receiver Channels (READ-ONLY)
+**Source**: RC channel handling in firmware
+
+18 RC channels (rc[0] through rc[17]), each with:
+- `value`: Raw channel value (1000-2000µs)
+- `low`: Channel < 1333µs
+- `mid`: Channel 1333-1666µs
+- `high`: Channel > 1666µs
+
+### 4. ✅ **gvar.js** - Global Variables (READ/WRITE)
+**Source**: `src/main/programming/global_variables.c`
+
+8 global variables (gvar[0] through gvar[7]):
+- Range: -1,000,000 to 1,000,000
+- Used for storing/sharing data between logic conditions
+
+### 5. ✅ **waypoint.js** - Waypoint Navigation (READ-ONLY)
+**Source**: `src/main/navigation/navigation_pos_estimator.c`
+
+Waypoint mission data:
+- **Current WP**: number, action
+- **Position**: latitude, longitude, altitude
+- **Navigation**: distance, bearing
+- **Status**: missionReached, missionValid
+
+### 6. ✅ **pid.js** - Programming PID Controllers
+**Source**: `src/main/programming/pid.c`
+
+4 PID controllers (pid[0] through pid[3]), each with:
+- `configure()` method: setpoint, measurement, p, i, d, ff
+- `output` property: Controller output
+- `enabled` property: Controller state
+
+### 7. ✅ **helpers.js** - Math & Utility Functions
+**Source**: `src/main/programming/logic_condition.c` (OPERATION_*)
+
+Math functions:
+- **Basic**: min, max, abs
+- **Trig**: sin, cos, tan (degrees)
+- **Mapping**: mapInput, mapOutput
+- **Arithmetic**: add, sub, mul, div, mod (operators)
+
+### 8. ✅ **events.js** - Event Handler Functions
+**Source**: Logic condition framework
+
+Event handlers:
+- **on.arm**: Execute after arming with delay
+- **on.always**: Execute every cycle
+- **when**: Execute when condition true
+- **sticky**: Execute between on/off conditions
+- **edge**: Execute on rising edge
+- **delay**: Execute after condition true for duration
+- **timer**: Execute on periodic timer
+- **whenChanged**: Execute when value changes
+
+### 9. ✅ **index.js** - Main Export
+Combines all definitions into single object.
+
+## Implementation Status
+
+| File | Status | Lines | Operands | Notes |
+|------|--------|-------|----------|-------|
+| flight.js | ✅ Ready | ~250 | FLIGHT(0-44) | All flight parameters |
+| override.js | ✅ Ready | ~150 | OPS(23-46) | All override operations |
+| rc.js | ✅ Ready | ~80 | RC(0-17) | 18 RC channels |
+| gvar.js | ✅ Ready | ~30 | GVAR(0-7) | 8 global variables |
+| waypoint.js | ✅ Ready | ~80 | WAYPOINT(0-8) | Waypoint nav data |
+| pid.js | ✅ Ready | ~70 | PID(0-3) | 4 PID controllers |
+| helpers.js | ✅ Ready | ~80 | OPS(14-39) | Math functions |
+| events.js | ✅ Ready | ~120 | - | Event handlers |
+| index.js | ✅ Ready | ~20 | - | Main export |
+
+## Operand Type Mapping
+
+From INAV firmware (`logic_condition.h`):
+
+```c
+typedef enum logicOperandType_s {
+    LOGIC_CONDITION_OPERAND_TYPE_VALUE = 0,       // Literal number
+    LOGIC_CONDITION_OPERAND_TYPE_RC_CHANNEL = 1,  // RC channel value
+    LOGIC_CONDITION_OPERAND_TYPE_FLIGHT = 2,      // Flight parameter (flight.js)
+    LOGIC_CONDITION_OPERAND_TYPE_FLIGHT_MODE = 3, // Flight mode
+    LOGIC_CONDITION_OPERAND_TYPE_LC = 4,          // Logic condition result
+    LOGIC_CONDITION_OPERAND_TYPE_GVAR = 5,        // Global variable (gvar.js)
+    LOGIC_CONDITION_OPERAND_TYPE_PID = 6,         // Programming PID (pid.js)
+    LOGIC_CONDITION_OPERAND_TYPE_WAYPOINTS = 7    // Waypoint (waypoint.js)
+} logicOperandType_e;
+```
+
+## Operation Mapping
+
+Key operations from firmware:
+
+```c
+// Conditionals
+OPERATION_TRUE = 0
+OPERATION_EQUAL = 1
+OPERATION_GREATER_THAN = 2
+OPERATION_LOWER_THAN = 3
+OPERATION_LOW = 4
+OPERATION_MID = 5
+OPERATION_HIGH = 6
+
+// Logical
+OPERATION_AND = 7
+OPERATION_OR = 8
+OPERATION_NOT = 12
+OPERATION_STICKY = 13
+
+// Arithmetic
+OPERATION_ADD = 14
+OPERATION_SUB = 15
+OPERATION_MUL = 16
+OPERATION_DIV = 17
+OPERATION_MOD = 18
+
+// Global Variables
+OPERATION_GVAR_SET = 19
+OPERATION_INC_GVAR = 20
+OPERATION_DEC_GVAR = 21
+
+// Overrides
+OPERATION_OVERRIDE_ARM_SAFETY = 23
+OPERATION_OVERRIDE_ARMING_DISABLED = 24
+OPERATION_OVERRIDE_THROTTLE_SCALE = 25
+OPERATION_OVERRIDE_THROTTLE = 26
+OPERATION_OVERRIDE_VTX_POWER = 27
+OPERATION_OVERRIDE_VTX_BAND = 28
+OPERATION_OVERRIDE_VTX_CHANNEL = 29
+
+// Math
+OPERATION_MIN = 30
+OPERATION_MAX = 31
+OPERATION_ABS = 32
+OPERATION_SIN = 35
+OPERATION_COS = 36
+OPERATION_TAN = 37
+OPERATION_MAP_INPUT = 38
+OPERATION_MAP_OUTPUT = 39
+```
+
+## Flight Parameter Values
+
+From firmware (`logic_condition.c`):
+
+```c
+LOGIC_CONDITION_OPERAND_FLIGHT_ARM_TIMER = 0
+LOGIC_CONDITION_OPERAND_FLIGHT_HOME_DISTANCE = 1
+LOGIC_CONDITION_OPERAND_FLIGHT_TRIP_DISTANCE = 2
+LOGIC_CONDITION_OPERAND_FLIGHT_RSSI = 3
+LOGIC_CONDITION_OPERAND_FLIGHT_VBAT = 4
+LOGIC_CONDITION_OPERAND_FLIGHT_CELL_VOLTAGE = 5
+LOGIC_CONDITION_OPERAND_FLIGHT_CURRENT = 6
+LOGIC_CONDITION_OPERAND_FLIGHT_MAH_DRAWN = 7
+LOGIC_CONDITION_OPERAND_FLIGHT_GPS_SATS = 9
+LOGIC_CONDITION_OPERAND_FLIGHT_GROUND_SPEED = 11
+LOGIC_CONDITION_OPERAND_FLIGHT_ALTITUDE = 12
+// ... and more
+```
+
+## Usage After Implementation
+
+Once these files are created:
+
+### 1. Analyzer Auto-Updates
+```javascript
+// analyzer.js automatically picks up new properties
+const apiDefinitions = require('./../api/definitions/index.js');
+this.inavAPI = this.buildAPIStructure(apiDefinitions);
+// No code changes needed!
+
+```
+
+### 2. Decompiler Auto-Updates
+```javascript
+// decompiler.js automatically maps operands
+this.operandToProperty = this.buildOperandMapping(apiDefinitions);
+// Decompiles FLIGHT(40) → inav.flight.compassHeading automatically
+
+```
+
+### 3. TypeScript Auto-Generation
+```javascript
+// types.js generates Monaco definitions
+const dts = generateTypeDefinitions(apiDefinitions);
+// IntelliSense shows all properties automatically
+
+```
+
+### 4. Adding New Properties
+To add `flight.newSensor`:
+
+1. Edit `flight.js`:
+```javascript
+newSensor: {
+  type: 'number',
+  desc: 'New sensor value',
+  inavOperand: { type: 2, value: 50 }
+}
+
+```
+
+2. Done! Everything updates automatically:
+   - ✅ Analyzer validates `flight.newSensor`
+   - ✅ Decompiler recognizes operand 50
+   - ✅ TypeScript shows in autocomplete
+   - ✅ Code generator uses correct operand
+
+## Verification Checklist
+
+After creating these files:
+
+- [ ] All files exist in `js/transpiler/api/definitions/`
+- [ ] `index.js` exports all definitions
+- [ ] Each property has `inavOperand` or `inavOperation`
+- [ ] Operand values match INAV firmware
+- [ ] Range values are correct
+- [ ] Readonly flags are correct
+- [ ] Nested objects are properly structured
+- [ ] `analyzer.js` imports and uses definitions
+- [ ] `decompiler.js` imports and uses definitions
+- [ ] `types.js` generates TypeScript correctly
+- [ ] Test transpilation works
+- [ ] Test decompilation works
+- [ ] Test Monaco autocomplete works
+
+## References
+
+- **INAV Source**: https://github.com/iNavFlight/inav
+  - `src/main/programming/logic_condition.c`
+  - `src/main/programming/logic_condition.h`
+  - `src/main/programming/global_variables.c`
+  - `src/main/programming/pid.c`
+- **Documentation**: Programming Framework.md
+- **Configurator**: programming.js, programming.html
+
+## Benefits
+
+✅ **Single Source of Truth**: One place to edit  
+✅ **Automatic Updates**: Add property → everything works  
+✅ **Type Safety**: Proper TypeScript generation  
+✅ **Maintainability**: Easy to keep in sync with INAV  
+✅ **Documentation**: Self-documenting API  
+✅ **Validation**: Comprehensive range/type checking
+
+## Maintenance
+
+When adding new properties or updating existing ones, see `api_maintenance_guide.md` for the complete workflow and best practices.