inav/docs/javascript_programming/TIMER_WHENCHANGED_IMPLEMENTATION.md

timer() and whenChanged() Functions

Overview

The timer() and whenChanged() functions provide advanced timing and change-detection capabilities for INAV logic programming.

timer() Function

Syntax

inav.events.timer(onMs, offMs, () => {
  // actions
});

Description

Execute actions on a periodic timer with on/off cycling. The action executes during the "on" period and pauses during the "off" period.

Parameters

• onMs: Duration in milliseconds to run the action
• offMs: Duration in milliseconds to wait between executions
• action: Arrow function containing actions to execute during on-time

Example

// Flash VTX power: ON for 1 second, OFF for 2 seconds, repeat
inav.events.timer(1000, 2000, () => {
  inav.override.vtx.power = 4;
});

Generated Logic Conditions:

logic 0 1 -1 49 0 1000 0 2000 0    # TIMER: ON 1000ms, OFF 2000ms
logic 1 1 0 25 0 0 0 0 4 0         # Set VTX power = 4

Validation Rules

• Requires exactly 3 arguments
• onMs must be numeric literal > 0
• offMs must be numeric literal > 0
• Third argument must be arrow function with actions

whenChanged() Function

Syntax

inav.events.whenChanged(value, threshold, () => {
  // actions
});

Description

Execute actions when a monitored value changes by more than the specified threshold. Uses a built-in 100ms detection window.

Parameters

• value: Flight parameter or global variable to monitor
• threshold: Minimum change required to trigger (numeric literal)
• action: Arrow function containing actions to execute on change

Example

// Log altitude whenever it changes by 50cm or more
inav.events.whenChanged(inav.flight.altitude, 50, () => {
  inav.gvar[0] = inav.flight.altitude;
});

Generated Logic Conditions:

logic 0 1 -1 50 2 12 0 50 0        # DELTA: altitude, threshold 50
logic 1 1 0 18 0 0 2 12 0          # gvar[0] = altitude

Validation Rules

• Requires exactly 3 arguments
• value must be a valid flight parameter or gvar
• threshold must be numeric literal > 0
• Third argument must be arrow function with actions

Round-Trip Support

Both functions support perfect round-trip transpilation/decompilation:

timer() Round-Trip

// Original JavaScript
inav.events.timer(1000, 2000, () => { inav.gvar[0] = 1; });

// Transpiled to logic conditions
logic 0 1 -1 49 0 1000 0 2000 0
logic 1 1 0 18 0 0 0 0 1 0

// Decompiled back to JavaScript
inav.events.timer(1000, 2000, () => {
  inav.gvar[0] = 1;
});

whenChanged() Round-Trip

// Original JavaScript
inav.events.whenChanged(inav.flight.altitude, 50, () => { inav.gvar[0] = inav.flight.altitude; });

// Transpiled to logic conditions
logic 0 1 -1 50 2 12 0 50 0
logic 1 1 0 18 0 0 2 12 0

// Decompiled back to JavaScript
inav.events.whenChanged(inav.flight.altitude, 50, () => {
  inav.gvar[0] = inav.flight.altitude;
});

API Definitions

Both functions are defined in api/definitions/events.js:

timer: {
  type: 'function',
  desc: 'Execute action on a periodic timer (on/off cycling)',
  params: {
    onMs: { type: 'number', unit: 'ms', desc: 'Duration to run action' },
    offMs: { type: 'number', unit: 'ms', desc: 'Duration to wait between executions' },
    action: { type: 'function', desc: 'Action to execute during on-time' }
  },
  example: 'inav.events.timer(1000, 5000, () => { inav.override.vtx.power = 4; })'
},

whenChanged: {
  type: 'function',
  desc: 'Execute when value changes by more than threshold',
  params: {
    value: { type: 'number', desc: 'Value to monitor' },
    threshold: { type: 'number', desc: 'Change threshold' },
    action: { type: 'function', desc: 'Action to execute on change' }
  },
  example: 'inav.events.whenChanged(inav.flight.altitude, 100, () => { inav.gvar[0] = inav.flight.altitude; })'
}

See Also

• TIMER_WHENCHANGED_EXAMPLES.md - More usage examples and patterns
• JAVASCRIPT_PROGRAMMING_GUIDE.md - Complete programming guide
• events.js - Full API definitions