inav/docs/javascript_programming/api_definitions_summary.md

# 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.