Sync inav to Gitea

docs/javascript_programming/index.md

@@ -0,0 +1,289 @@
+# INAV JavaScript Programming Documentation
+
+Complete documentation for the INAV JavaScript transpiler that allows programming flight controller logic conditions in JavaScript.
+
+## 📚 Table of Contents
+
+- [Quick Start](#quick-start)
+- [User Guides](#user-guides)
+- [Developer Documentation](#developer-documentation)
+- [Features](#features)
+
+---
+
+## Quick Start
+
+The INAV JavaScript transpiler converts JavaScript code into INAV logic conditions, enabling you to program flight controller behavior using familiar JavaScript syntax instead of raw logic condition commands.
+
+### Features at a Glance
+
+**✨ Modern Development Experience**
+
+![IntelliSense Autocomplete](intellisense.png)
+*Real-time autocomplete with type information and documentation*
+
+![Helpful Warnings](warnings.png)
+*Clear error messages with line numbers and suggestions*
+
+### Basic Example
+
+```javascript
+
+// Increase VTX power when far from home
+if (inav.flight.homeDistance > 500) {
+  inav.override.vtx.power = 4;
+}
+
+```
+
+![VTX Power Control Example](example_vtx_power.png)
+*Complete example showing VTX power control based on distance*
+
+### RC Channel Override Example
+
+![RC Override Example](example_override_rc.png)
+*Using RC channels to control behavior*
+
+---
+
+## User Guides
+
+### 📖 [JavaScript Programming Guide](JAVASCRIPT_PROGRAMMING_GUIDE.md)
+**Start here if you're new to INAV JavaScript programming**
+
+Quick reference covering:
+- Pattern guide: `if`, `edge()`, `sticky()`, `delay()`, `timer()`, `whenChanged()`
+- Common patterns (initialization, event counting, debouncing)
+- Key differences between patterns
+- Available objects and APIs
+- Debugging techniques
+
+### 🔧 [Operations Reference](OPERATIONS_REFERENCE.md)
+**Complete reference for all supported operations**
+
+Comprehensive guide to all INAV logic condition operations:
+- ✅ Arithmetic: `+`, `-`, `*`, `/`, `%`
+- ✅ Comparisons: `===`, `>`, `<`, `approxEqual()`
+- ✅ Logical: `&&`, `||`, `!`, `xor()`, `nand()`, `nor()`
+- ✅ Math: `Math.min()`, `Math.max()`, `Math.sin()`, `Math.cos()`, `Math.tan()`, `Math.abs()`
+- ✅ Scaling: `mapInput()`, `mapOutput()`
+- ✅ Flow control: `edge()`, `sticky()`, `delay()`, `timer()`, `whenChanged()`
+- ✅ Variables: `gvar[0-7]`, `let`, `var`
+- ✅ Overrides: `override.vtx.*`, `override.throttle`, `override.armSafety`, etc.
+- ✅ RC channel states: `rc[n].low`, `rc[n].mid`, `rc[n].high`, `rc[n].value`
+
+Includes usage examples and notes for each operation.
+
+### ⏱️ [Timer and WhenChanged Examples](TIMER_WHENCHANGED_EXAMPLES.md)
+**Practical examples for time-based and change-detection patterns**
+
+Examples covering:
+- Timer patterns (blinking, cycling, periodic actions)
+- Change detection (RSSI monitoring, altitude tracking)
+- Combined patterns with multiple conditions
+- Real-world use cases
+
+---
+
+## Developer Documentation
+
+### 🏗️ [Technical Implementation Overview](implementation_summary.md)
+**Architecture and design of the transpiler system**
+
+Covers:
+- System architecture and component interaction
+- Transpiler pipeline (Parser → Analyzer → Optimizer → Codegen)
+- Decompiler pattern recognition
+- Key features and capabilities
+- Integration with Monaco Editor
+
+### 🧪 [Testing Guide](TESTING_GUIDE.md)
+**How to test changes to the transpiler**
+
+Essential reading before making changes:
+- Which components need updates (parser, analyzer, codegen, decompiler)
+- Round-trip testing template (JavaScript → CLI → JavaScript)
+- Common issues and solutions
+- Verification checklist
+- Step-by-step example of adding a new operation
+
+**Always use round-trip testing when modifying the transpiler!**
+
+### 🔌 [API Definitions Summary](api_definitions_summary.md)
+**Structure of the INAV API definitions**
+
+Documents the API definition system:
+- Available API objects (`flight`, `override`, `rc`, `gvar`, `waypoint`, etc.)
+- Property types and metadata
+- INAV operand mappings
+- How definitions drive IntelliSense
+
+### 🛠️ [API Maintenance Guide](api_maintenance_guide.md)
+**How to add, modify, or maintain API definitions**
+
+Step-by-step instructions for:
+- Adding new properties to existing APIs
+- Creating new API objects
+- Updating operand mappings
+- Testing API changes
+- Common pitfalls
+
+### ⏲️ [Timer and WhenChanged Implementation](TIMER_WHENCHANGED_IMPLEMENTATION.md)
+**Technical details of TIMER and DELTA operations**
+
+Implementation guide for:
+- How TIMER operation works (operations 49)
+- How DELTA operation works (operation 50)
+- AST representation
+- Code generation strategy
+- Decompiler pattern recognition
+
+### ⚙️ [Generate Constants README](GENERATE_CONSTANTS_README.md)
+**How to regenerate INAV constants from firmware**
+
+Instructions for:
+- Extracting operation codes from firmware
+- Regenerating `inav_constants.js`
+- Keeping constants in sync with firmware
+- What to do when firmware adds new operations
+
+---
+
+## Features
+
+### Bidirectional Translation
+
+- **Transpiler**: JavaScript → INAV Logic Conditions
+- **Decompiler**: INAV Logic Conditions → JavaScript
+- **Round-trip capable**: Code survives transpile/decompile cycles
+
+### Development Experience
+
+- **Monaco Editor Integration**: Full-featured code editor
+- **IntelliSense**: Context-aware autocomplete with documentation
+- **Real-time Validation**: Immediate feedback on syntax errors
+- **Syntax Highlighting**: JavaScript syntax with INAV-specific extensions
+- **Error Messages**: Clear, actionable error messages with line numbers
+
+### Language Support
+
+**All INAV Operations Supported:**
+- Arithmetic operations
+- Comparison and logical operations
+- Math functions (trigonometry, min/max)
+- Flow control (edge detection, sticky conditions, delays, timers)
+- Variable management (global variables, let/var)
+- RC channel access and state detection
+- Flight parameter overrides
+- Waypoint navigation
+
+**JavaScript Features:**
+- Namespaced API access: `inav.flight.*`, `inav.override.*`, `inav.events.*`
+- `let`/`const` variables: compile-time constant substitution
+- `var` variables: allocated to global variables
+- Ternary operator: `condition ? value1 : value2`
+- Arrow functions: `() => condition`
+- Object property access: `inav.flight.altitude`, `inav.rc[0].value`
+- Binary expressions: `+`, `-`, `*`, `/`, `%`
+- Comparison operators: `>`, `<`, `===`
+- Logical operators: `&&`, `||`, `!`
+- Math methods: `Math.min()`, `Math.max()`, `Math.sin()`, etc.
+- Flight mode detection: `inav.flight.mode.poshold`, `inav.flight.mode.rth`, etc.
+- PID controller outputs: `inav.pid[0-3].output`
+
+### Validation
+
+- Property access validation against API definitions
+- Range checking (gvar indices, heading values, etc.)
+- Type checking for function arguments
+- Dead code detection
+- Uninitialized variable detection
+- Helpful suggestions for common mistakes
+
+### Optimization
+
+- Common Subexpression Elimination (CSE)
+- Efficient operand usage
+- Optimized GVAR_INC/GVAR_DEC generation
+- Minimal logic condition count
+
+---
+
+## File Organization
+
+```
+js/transpiler/
+├── docs/                          # Documentation (this directory)
+│   ├── index.md                   # This file - documentation index
+│   ├── JAVASCRIPT_PROGRAMMING_GUIDE.md    # User guide
+│   ├── OPERATIONS_REFERENCE.md            # All operations
+│   ├── TIMER_WHENCHANGED_EXAMPLES.md      # Timer/change examples
+│   ├── implementation_summary.md          # Technical overview
+│   ├── TESTING_GUIDE.md                   # Testing workflow
+│   ├── api_definitions_summary.md         # API structure
+│   ├── api_maintenance_guide.md           # API maintenance
+│   ├── GENERATE_CONSTANTS_README.md       # Constants generation
+│   ├── TIMER_WHENCHANGED_IMPLEMENTATION.md # Implementation details
+│   ├── intellisense.png                   # Screenshot: autocomplete
+│   ├── warnings.png                       # Screenshot: errors
+│   ├── example_vtx_power.png              # Screenshot: VTX example
+│   └── example_override_rc.png            # Screenshot: RC example
+├── api/                           # API definitions
+│   └── definitions/               # INAV API object definitions
+├── editor/                        # Monaco editor integration
+│   ├── monaco_setup.js            # Editor configuration
+│   ├── intellisense.js            # Autocomplete provider
+│   └── diagnostics.js             # Real-time validation
+├── transpiler/                    # Core transpiler
+│   ├── index.js                   # Main transpiler entry point
+│   ├── parser.js                  # JavaScript parser (Acorn wrapper)
+│   ├── analyzer.js                # Semantic analysis
+│   ├── optimizer.js               # Code optimization (CSE)
+│   ├── codegen.js                 # INAV command generation
+│   ├── decompiler.js              # INAV → JavaScript
+│   ├── inav_constants.js          # Operation codes and types
+│   ├── variable_handler.js        # let/var variable management
+│   ├── arrow_function_helper.js   # Arrow function utilities
+│   └── error_handler.js           # Error collection
+└── tools/                         # Build tools
+    └── generate-constants.js      # Extract constants from firmware
+```
+
+---
+
+## Getting Help
+
+### Common Questions
+
+**Q: Which pattern should I use?**
+- Use `if` for continuous control (checking every cycle)
+- Use `edge()` for one-time actions when condition becomes true
+- Use `sticky()` for latching conditions with hysteresis
+- Use `delay()` for actions that need sustained conditions
+- Use `timer()` for periodic toggling
+- Use `whenChanged()` for detecting value changes
+
+See the [JavaScript Programming Guide](JAVASCRIPT_PROGRAMMING_GUIDE.md) for detailed examples.
+
+**Q: How do I debug my code?**
+Use global variables to track state and view them in the OSD or configurator. See the debugging section in the [JavaScript Programming Guide](JAVASCRIPT_PROGRAMMING_GUIDE.md).
+
+**Q: What operations are supported?**
+All INAV logic condition operations! See [Operations Reference](OPERATIONS_REFERENCE.md) for the complete list.
+
+**Q: How do I contribute?**
+Read the [Testing Guide](TESTING_GUIDE.md) to understand the testing workflow, then make your changes ensuring all 4 components (parser, analyzer, codegen, decompiler) are updated and round-trip tested.
+
+---
+
+## Version History
+
+**2025-11-25**: Complete implementation
+- All INAV logic condition operations now supported
+- RC channel state detection (LOW/MID/HIGH)
+- XOR/NAND/NOR logical operations
+- APPROX_EQUAL comparison
+- MAP_INPUT/MAP_OUTPUT scaling
+- Comprehensive documentation
+
+**Last Updated**: 2025-11-25