DOCSEARCHbyAlgolia
Submit Docs

Moddable SDK Documentation

repository·public·Indexed 23 days ago

https://github.com/moddable-opensource/moddable

A development environment for microcontrollers using the XS JavaScript engine to run compliant JavaScript on resource-constrained hardware. Includes documentation for BLE HID host/mod architecture, Conversational AI integration with various API services, Giphy application setup, and hardware-specific configurations for Moddable Six and Moddable Two.

Tokens
248.6K
Snippets
630
Records
1.2K
Agent score
79%

What's inside Moddable SDK

  1. Overview of Firmata implementation in Moddable SDK

    public

    The Moddable SDK provides an implementation of the Firmata protocol, which allows for hardware control communication between two devices (typically a computer acting as a client and a microcontroller acting as a server).

    This implementation is built using the proposed Ecma TC53 IO classes, providing a consistent API for hardware resources like digital/analog IO, I2C, and serial ports.

    Key Constraints & Characteristics:

    • Target Hardware: The IO Class implementation is currently available only for the ESP8266 microcontroller.
    • Protocol Nature: Firmata is a client/server protocol. The microcontroller acts as the server, and the controller (e.g., a computer running Firmata.js) acts as the client.
    • Transport: While often used over Serial (default baud rate 57600), it can be carried over any bi-directional connection, such as TCP.
    • Assumptions: The protocol assumes a reliable transport (no built-in checksums/retransmits), near real-time connection (no timestamps), and a single client connection (no resource locking mechanism).

  2. Overview of the Moddable SDK

    public

    The Moddable SDK is a suite of development tools and runtime software designed to create applications for highly constrained microcontrollers. It enables modern software development on devices that typically have limited resources, such as ~45 KB of free memory, 1 MB of Flash ROM, and 80 MHz clock speeds.

    Key characteristics include:

    • Primary Language: JavaScript, powered by the XS JavaScript engine which implements the 2025 JavaScript language standard with >99% conformance.
    • Efficiency Focus: Designed to minimize memory use through specialized APIs and build-time optimizations.
    • Implementation: Primarily implemented in JavaScript, with performance-critical portions or native API access implemented in C (no C++ is used).
    • Build-Time Optimization: Significant effort is placed on build-time tools to ensure efficient execution on constrained hardware.

  3. Introduction to the Poco renderer

    public

    Poco is a renderer used within the Moddable SDK. This documentation provides a guide to working with Poco, covering core concepts through practical examples and providing a full API reference for both JavaScript and C.

    Key areas covered include:

    • Drawing primitives (Rectangles, Origins, Clipping)
    • Bitmap handling (Monochrome, Color, Gray, Offscreen, and Patterns)
    • Advanced rendering (Alpha blending, JPEG, Text, Rotation)
    • Pixel format specifications for destinations, displays, and source bitmaps.

  4. Overview of Moddable SDK documentation structure

    public

    The Moddable SDK documentation is organized into several key subdirectories that follow a consistent structure:

    • commodetto: Resources for the Commodetto bitmap graphics library (2D graphics API) and the Poco rendering engine.
    • piu: Resources for the Piu user interface framework (complex, responsive layouts).
    • networking: Resources for BLE, network sockets, and protocols like HTTP/HTTPS, MQTT, WebSockets, DNS, SNTP, and telnet.
    • io: Resources for hardware protocols (digital, analog, PWM, I²C, etc.) using ECMA-419, including driver documentation and sensor examples.

  5. Overview of JSONParser for embedded systems

    public

    The JSONParser module is designed for parsing JSON data streams in memory-constrained embedded environments. It supports character-by-character extraction in C for high efficiency and provides JavaScript interfaces for two primary use cases:

    1. Key-based extraction: Constructing a simplified JSON tree containing only specified keys.
    2. Pattern-based extraction: Using matching functions to extract specific data points into a custom data structure without building a full JSON tree.

    The module uses Ragel to generate its state-machine-based parser code, ensuring robust and efficient processing.

  6. Overview of Home Assistant example projects

    public

    These examples demonstrate how to use the official Home Assistant WebSocket package within the Moddable ecosystem. They are built using mcpack, the Moddable SDK's bridge to npm modules.

    Available Examples:

    • discover: Lists all entities currently in the Home Assistant registry.
    • blink: Toggles a light on and off every 30 seconds using a timer; it subscribes to the light's state to maintain synchronization.
    • blink-ts: The TypeScript implementation of the blink example.
    • button: Similar to blink, but uses the device's physical default button to toggle the light instead of a timer.

  7. Explore Moddable SDK Driver Examples

    public

    The Moddable SDK provides a wide range of driver examples for various sensors, displays, and touch controllers. These examples demonstrate how to interface with hardware using the SDK's drivers.

    Key Information:

    • Driver Source Code: The actual driver implementations used in these examples are located in the $MODDABLE/modules/drivers directory.
    • Usage: You can use these examples to understand how to implement specific hardware protocols (I2C, SPI, 1-Wire) or to see how specific components (like the Arducam camera or BMP280 sensor) are integrated into Moddable applications.

  8. Available TCP IO Examples in Moddable SDK

    public

    The following examples demonstrate various networking implementations built on top of the ECMA-419 TCP socket:

    HTTP

    • simplehttpget: A bare-bones example of making an HTTP request using a TCP socket directly (intended for educational purposes, not production).
    • httpclient: An HTTP client API implementing the HTTPRequest class.
    • fetch: An implementation of the standard HTML5 fetch API (supports HTTPS).

    HTTPS

    • httpsclient: Combines TLS TCP socket with httpclient to perform secure requests.

    WebSocket

    • websocketclient: A WebSocket client API implementing the WebSocketClient class.
    • websocketsclient: Combines TLS TCP socket with websocketclient for secure wss:// connections.
    • websocket: An implementation of the standard HTML WebSocket API.

    MQTT

    • mqttclient: An MQTT client API implementing the MQTTClient class.
    • mqttsclient: Combines TLS TCP socket with mqttclient for secure mqtts:// connections.
    • mqtt: An implementation of the MQTT.js package built on the MQTTClient API.

    Server Sent Events (SSE)

    • eventsource: An implementation of the standard HTML EventSource API for receiving server-sent events, built on the HTTP client API.

  9. About Moddable Six Hardware

    public

    Moddable Six (Revision 1.1) is a development board powered by a dual-core ESP32-S3 MCU. It features 8 MB of flash storage and 8 MB of PSRAM (8.5 MB total RAM) connected via an 8-bit bus for high throughput.

    Key hardware components include:

    • Display: 240 x 320 QVGA IPS display with an 8-bit wide parallel data bus and adjustable brightness.
    • Touch: GT911 multi-touch controller with hardware interrupts for high responsiveness.
    • Audio: Built-in amplified speaker and a TDK T3902 MEMS microphone for PDM audio capture.
    • Connectivity: STEMMA QT / Qwiic / JST SH 1mm connector for I²C peripherals.
    • Indicators: Onboard NeoPixel (multi-color LED).
    • Debugging: Supports programming and JavaScript debugging over USB, including GDB for native code.

  10. Use Moddable developer tools

    public

    The SDK includes several command-line tools and configuration mechanisms:

    • Build Tools: Includes mcconfig, mcrez, png2bmp, xsc, xsl, and a desktop simulator.
    • Project Configuration: Projects are configured using JSON manifest files. These manifests are used to define the build configuration and can also be used to configure native code options via Defines.

  11. Explore Piu UI Framework Examples

    public

    The Piu examples demonstrate how to use the Piu object-based user interface framework to create complex, responsive layouts. Most examples are designed for a QVGA (320x240) screen but feature responsive layouts that adapt to various sizes. Most examples run on the desktop simulator, except for backlight, epaper-travel-time, one-line, and one-line-keyboard which require specific hardware or environments.

    Key feature categories covered in the examples:

    • Images: Rendering GIFs, JPEGs, and PNGs (images, balls, neon-light).
    • Text: Rendering various styles, sizes, and alignments (text, cards, localization).
    • Animation: Using Timeline, Transition, and built-in easing equations (easing-equations, transitions, timeline).
    • Touch Input: Implementing drag and multitouch (drag, drag-color, map-puzzle, keyboard).
    • Scrolling: Creating vertical and horizontal scrolling content (scroller, list).
    • Networking: Handling Wi-Fi configuration and HTTP requests for weather data (wifi-config, weather, mini-weather).

  12. Understand the Moddable SDK source tree structure

    public

    The repository is organized into several top-level directories that define the SDK's capabilities and tools:

    • build: Target-specific files for microcontrollers, simulators, and make files.
    • contributed: Unofficial projects and modules demonstrating Moddable API techniques.
    • documentation: Markdown-formatted documentation for the SDK.
    • examples: Example applications for various SDK capabilities.
    • licenses: License agreements and Contributor License Agreements.
    • modules: The runtime software modules (networking, graphics, UI, hardware, etc.). Most have a JavaScript API and are partially implemented in C.
    • tools: Build tools for image conversion, compression, rotation, font compression, localization, resource compilation, and application building from JSON manifests. Includes xsbug (the XS source level debugger).
    • xs: The XS JavaScript engine, including its compiler, linker, and test262 execution shell.