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):

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:

// 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):

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

// 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

// decompiler.js automatically maps operands
this.operandToProperty = this.buildOperandMapping(apiDefinitions);
// Decompiles FLIGHT(40) → inav.flight.compassHeading automatically

3. TypeScript Auto-Generation

// 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:

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.