Skip to content

Commit 22203ed

Browse files
committed
Docs: Convert JavaScript guide to use only namespaced syntax
Updates JavaScript programming documentation to use only namespaced syntax (inav.flight.*, inav.override.*, etc.) instead of destructuring. Preserves all new INAV 9.0 features: - PID controller output access (inav.pid[0-3].output) - Flight mode detection (inav.flight.mode.poshold, etc.) - Let/const variables for compile-time named expressions - Ternary operator support Changes: - Remove all destructuring syntax (const { flight, override } = inav) - Convert all examples to use fully-qualified namespaced access - Simplify sticky() documentation to show only callback syntax - Update event functions to use inav.events.* namespace This provides clearer, more explicit code examples that make it obvious where each identifier comes from.
1 parent 2dad940 commit 22203ed

File tree

1 file changed

+71
-125
lines changed

1 file changed

+71
-125
lines changed

docs/javascript_programming/JAVASCRIPT_PROGRAMMING_GUIDE.md

Lines changed: 71 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,9 @@ conditions behind the scenes.
2222
Use `if` statements for conditions that should check and execute **every cycle**:
2323

2424
```javascript
25-
const { flight, override } = inav;
26-
2725
// Checks every cycle - adjusts VTX power continuously
28-
if (flight.homeDistance > 100) {
29-
override.vtx.power = 3;
26+
if (inav.flight.homeDistance > 100) {
27+
inav.override.vtx.power = 3;
3028
}
3129
```
3230

@@ -38,12 +36,10 @@ if (flight.homeDistance > 100) {
3836
Use `edge()` for actions that should execute **only once** when a condition becomes true:
3937

4038
```javascript
41-
const { flight, gvar, edge } = inav;
42-
4339
// Executes ONCE when armTimer reaches 1000ms
44-
edge(() => flight.armTimer > 1000, { duration: 0 }, () => {
45-
gvar[0] = flight.yaw; // Save initial heading
46-
gvar[1] = 0; // Initialize counter
40+
inav.events.edge(() => inav.flight.armTimer > 1000, { duration: 0 }, () => {
41+
inav.gvar[0] = inav.flight.yaw; // Save initial heading
42+
inav.gvar[1] = 0; // Initialize counter
4743
});
4844
```
4945

@@ -61,45 +57,20 @@ edge(() => flight.armTimer > 1000, { duration: 0 }, () => {
6157
---
6258

6359
### Latching/Sticky Conditions
64-
Use `sticky()` for conditions that latch ON and stay ON until reset.
65-
66-
**Option 1: Variable assignment syntax** (recommended when you need to reference the latch state):
60+
Use `sticky()` for conditions that latch ON and stay ON until reset:
6761

6862
```javascript
69-
const { flight, gvar, sticky, override } = inav;
70-
71-
// Create a latch: ON when RSSI < 30, OFF when RSSI > 70
72-
var rssiWarning = sticky({
73-
on: () => flight.rssi < 30,
74-
off: () => flight.rssi > 70
75-
});
76-
77-
// Use the latch to control actions
78-
if (rssiWarning) {
79-
override.vtx.power = 4; // Max power while latched
80-
}
81-
```
82-
83-
**Option 2: Callback syntax** (simpler when actions are self-contained):
84-
85-
```javascript
86-
const { flight, sticky, override } = inav;
87-
8863
// Latch ON when RSSI < 30, OFF when RSSI > 70
89-
sticky(
90-
() => flight.rssi < 30, // ON condition
91-
() => flight.rssi > 70, // OFF condition
64+
inav.events.sticky(
65+
() => inav.flight.rssi < 30, // ON condition
66+
() => inav.flight.rssi > 70, // OFF condition
9267
() => {
93-
override.vtx.power = 4; // Executes while latched
68+
inav.override.vtx.power = 4; // Executes while latched
9469
}
9570
);
9671
```
9772

98-
**Parameters (variable syntax):**
99-
- **on**: Condition that latches ON
100-
- **off**: Condition that latches OFF
101-
102-
**Parameters (callback syntax):**
73+
**Parameters:**
10374
- **onCondition**: When to latch ON
10475
- **offCondition**: When to latch OFF
10576
- **action**: What to do while latched
@@ -115,11 +86,9 @@ sticky(
11586
Use `delay()` to execute after a condition has been true for a duration:
11687

11788
```javascript
118-
const { flight, gvar, delay } = inav;
119-
12089
// Executes only if RSSI < 30 for 2 seconds continuously
121-
delay(() => flight.rssi < 30, { duration: 2000 }, () => {
122-
gvar[0] = 1; // Set failsafe flag
90+
inav.events.delay(() => inav.flight.rssi < 30, { duration: 2000 }, () => {
91+
inav.gvar[0] = 1; // Set failsafe flag
12392
});
12493
```
12594

@@ -139,74 +108,63 @@ delay(() => flight.rssi < 30, { duration: 2000 }, () => {
139108

140109
### Initialize on Arm
141110
```javascript
142-
const { flight, gvar, edge } = inav;
143-
144-
edge(() => flight.armTimer > 1000, { duration: 0 }, () => {
145-
gvar[0] = 0; // Reset counter
146-
gvar[1] = flight.yaw; // Save heading
147-
gvar[2] = flight.altitude; // Save starting altitude
111+
inav.events.edge(() => inav.flight.armTimer > 1000, { duration: 0 }, () => {
112+
inav.gvar[0] = 0; // Reset counter
113+
inav.gvar[1] = inav.flight.yaw; // Save heading
114+
inav.gvar[2] = inav.flight.altitude; // Save starting altitude
148115
});
149116
```
150117

151118
### Count Events
152119
```javascript
153-
const { flight, gvar, edge } = inav;
154-
155120
// Initialize
156-
edge(() => flight.armTimer > 1000, { duration: 0 }, () => {
157-
gvar[0] = 0;
121+
inav.events.edge(() => inav.flight.armTimer > 1000, { duration: 0 }, () => {
122+
inav.gvar[0] = 0;
158123
});
159124

160125
// Count each time RSSI drops below 30 (counts transitions, not duration)
161-
edge(() => flight.rssi < 30, { duration: 100 }, () => {
162-
gvar[0] = gvar[0] + 1;
126+
inav.events.edge(() => inav.flight.rssi < 30, { duration: 100 }, () => {
127+
inav.gvar[0] = inav.gvar[0] + 1;
163128
});
164129
```
165130

166131
### Debounce Noisy Signals
167132
```javascript
168-
const { flight, override, edge } = inav;
169-
170133
// Only trigger if RSSI < 30 for at least 500ms
171-
edge(() => flight.rssi < 30, { duration: 500 }, () => {
172-
override.vtx.power = 4;
134+
inav.events.edge(() => inav.flight.rssi < 30, { duration: 500 }, () => {
135+
inav.override.vtx.power = 4;
173136
});
174137
```
175138

176139
### Multi-Stage Logic
177140
```javascript
178-
const { flight, override } = inav;
179-
180141
// Stage 1: Far away
181-
if (flight.homeDistance > 500) {
182-
override.vtx.power = 4;
142+
if (inav.flight.homeDistance > 500) {
143+
inav.override.vtx.power = 4;
183144
}
184145

185-
// Stage 2: Medium distance
186-
if (flight.homeDistance > 200 && flight.homeDistance <= 500) {
187-
override.vtx.power = 3;
146+
// Stage 2: Medium distance
147+
if (inav.flight.homeDistance > 200 && inav.flight.homeDistance <= 500) {
148+
inav.override.vtx.power = 3;
188149
}
189150

190151
// Stage 3: Close to home
191-
if (flight.homeDistance <= 200) {
192-
override.vtx.power = 2;
152+
if (inav.flight.homeDistance <= 200) {
153+
inav.override.vtx.power = 2;
193154
}
194155
```
195156

196157
### Hysteresis/Deadband
197158
```javascript
198-
const { flight, gvar, sticky, override } = inav;
199-
200159
// Turn ON at low voltage, turn OFF when recovered
201-
var lowVoltageWarning = sticky({
202-
on: () => flight.cellVoltage < 330, // Warning threshold
203-
off: () => flight.cellVoltage > 350 // Recovery threshold
204-
});
205-
206-
if (lowVoltageWarning) {
207-
override.throttleScale = 50; // Reduce throttle while in warning
208-
gvar[0] = 1; // Warning flag
209-
}
160+
inav.events.sticky(
161+
() => inav.flight.cellVoltage < 330, // Warning threshold
162+
() => inav.flight.cellVoltage > 350, // Recovery threshold
163+
() => {
164+
inav.override.throttleScale = 50; // Reduce throttle while in warning
165+
inav.gvar[0] = 1; // Warning flag
166+
}
167+
);
210168
```
211169

212170
---
@@ -229,16 +187,14 @@ if (lowVoltageWarning) {
229187
Use `let` or `const` to define reusable expressions that are compiled into the logic:
230188

231189
```javascript
232-
const { flight, override } = inav;
233-
234190
// Define reusable calculations
235191
let distanceThreshold = 500;
236192
let altitudeLimit = 100;
237-
let combinedCondition = flight.homeDistance > distanceThreshold && flight.altitude > altitudeLimit;
193+
let combinedCondition = inav.flight.homeDistance > distanceThreshold && inav.flight.altitude > altitudeLimit;
238194

239195
// Use in conditions
240196
if (combinedCondition) {
241-
override.vtx.power = 4;
197+
inav.override.vtx.power = 4;
242198
}
243199
```
244200

@@ -247,24 +203,22 @@ if (combinedCondition) {
247203
- Compiler automatically optimizes duplicate expressions
248204
- Variables preserve their custom names through compile/decompile cycles
249205

250-
**Important:** `let`/`const` variables are **compile-time substituted**, not runtime variables. For runtime state, use `gvar[]`.
206+
**Important:** `let`/`const` variables are **compile-time substituted**, not runtime variables. For runtime state, use `inav.gvar[]`.
251207

252208
### Ternary Operator
253209

254210
Use ternary expressions for conditional values:
255211

256212
```javascript
257-
const { flight, override } = inav;
258-
259213
// Assign based on condition
260-
let throttleLimit = flight.cellVoltage < 330 ? 25 : 50;
214+
let throttleLimit = inav.flight.cellVoltage < 330 ? 25 : 50;
261215

262-
if (flight.cellVoltage < 350) {
263-
override.throttleScale = throttleLimit;
216+
if (inav.flight.cellVoltage < 350) {
217+
inav.override.throttleScale = throttleLimit;
264218
}
265219

266220
// Inline in expressions
267-
override.vtx.power = flight.homeDistance > 500 ? 4 : 2;
221+
inav.override.vtx.power = inav.flight.homeDistance > 500 ? 4 : 2;
268222
```
269223

270224
**Use when:** You need conditional value assignment in a single expression.
@@ -273,33 +227,29 @@ override.vtx.power = flight.homeDistance > 500 ? 4 : 2;
273227

274228
## Available Objects
275229

276-
```javascript
277-
const {
278-
flight, // Flight telemetry (including flight.mode.*)
279-
override, // Override flight parameters
280-
rc, // RC channels
281-
gvar, // Global variables (0-7)
282-
pid, // Programming PID outputs (pid[0-3].output)
283-
waypoint, // Waypoint navigation
284-
edge, // Edge detection
285-
sticky, // Latching conditions
286-
delay // Delayed execution
287-
} = inav;
288-
```
230+
The `inav` namespace provides access to all flight controller data and control functions:
231+
232+
- `inav.flight` - Flight telemetry (including `flight.mode.*`)
233+
- `inav.override` - Override flight parameters
234+
- `inav.rc` - RC channels
235+
- `inav.gvar` - Global variables (0-7)
236+
- `inav.pid` - Programming PID outputs (`pid[0-3].output`)
237+
- `inav.waypoint` - Waypoint navigation
238+
- `inav.events.edge` - Edge detection
239+
- `inav.events.sticky` - Latching conditions
240+
- `inav.events.delay` - Delayed execution
289241

290242
### Flight Mode Detection
291243

292-
Check which flight modes are currently active via `flight.mode.*`:
244+
Check which flight modes are currently active via `inav.flight.mode.*`:
293245

294246
```javascript
295-
const { flight, gvar, override } = inav;
296-
297-
if (flight.mode.poshold === 1) {
298-
gvar[0] = 1; // Flag: in position hold
247+
if (inav.flight.mode.poshold === 1) {
248+
inav.gvar[0] = 1; // Flag: in position hold
299249
}
300250

301-
if (flight.mode.rth === 1) {
302-
override.vtx.power = 4; // Max power during RTH
251+
if (inav.flight.mode.rth === 1) {
252+
inav.override.vtx.power = 4; // Max power during RTH
303253
}
304254
```
305255

@@ -310,23 +260,21 @@ if (flight.mode.rth === 1) {
310260
Read output values from the 4 programming PID controllers (configured in Programming PID tab):
311261

312262
```javascript
313-
const { pid, gvar, override } = inav;
314-
315-
if (pid[0].output > 500) {
316-
override.throttle = 1600;
263+
if (inav.pid[0].output > 500) {
264+
inav.override.throttle = 1600;
317265
}
318266

319-
gvar[0] = pid[0].output; // Store for OSD display
267+
inav.gvar[0] = inav.pid[0].output; // Store for OSD display
320268
```
321269

322-
**Available:** `pid[0].output` through `pid[3].output`
270+
**Available:** `inav.pid[0].output` through `inav.pid[3].output`
323271

324272
---
325273

326274
## Tips
327275

328-
1. **Initialize variables on arm** using `edge()` with `flight.armTimer > 1000`
329-
2. **Use gvars for state** - they persist between logic condition evaluations
276+
1. **Initialize variables on arm** using `inav.events.edge()` with `inav.flight.armTimer > 1000`
277+
2. **Use inav.gvar for state** - they persist between logic condition evaluations
330278
3. **edge() duration = 0** means instant trigger on condition becoming true
331279
4. **edge() duration > 0** adds debounce time
332280
5. **if statements are continuous** - they execute every cycle
@@ -339,16 +287,14 @@ gvar[0] = pid[0].output; // Store for OSD display
339287

340288
Use global variables to track state:
341289
```javascript
342-
const { flight, gvar, edge } = inav;
343-
344290
// Debug counter
345-
edge(() => flight.armTimer > 1000, { duration: 0 }, () => {
346-
gvar[7] = 0; // Use gvar[7] as debug counter
291+
inav.events.edge(() => inav.flight.armTimer > 1000, { duration: 0 }, () => {
292+
inav.gvar[7] = 0; // Use gvar[7] as debug counter
347293
});
348294

349295
// Increment on each event
350-
edge(() => flight.rssi < 30, { duration: 0 }, () => {
351-
gvar[7] = gvar[7] + 1;
296+
inav.events.edge(() => inav.flight.rssi < 30, { duration: 0 }, () => {
297+
inav.gvar[7] = inav.gvar[7] + 1;
352298
});
353299

354300
// Check gvar[7] value in OSD or Configurator to see event count

0 commit comments

Comments
 (0)