First try for a new documentation

Place where find documentation
User avatar
cicciocb
Site Admin
Posts: 2781
Joined: Mon Feb 03, 2020 1:15 pm
Location: Toulouse
Has thanked: 592 times
Been thanked: 1989 times
Contact:

First try for a new documentation

Post by cicciocb »

Hi all,
Given the tremendous feedback and suggestions I recently received :lol:, I’ve teamed up with a good friend to draft a new document aimed at helping new users discover Annex. Feel free to let me know if you'd like any further adjustments!

We drafted this first chapter, the goal is complete the document with 7 - 8 chapters drafted in the same style.

You'll find below the 1st pass.
As usual, I'm bracing myself (or not) for the incoming tsunami of your comments and suggestions. Brace for impact!


Chapter 1: Introduction to Annex RDS for ESP32
Annex RDS is a powerful, easy-to-use firmware for ESP32 microcontrollers that allows you to program the device using a web-based IDE, simplifying the development of IoT applications. This system allows developers to write and execute code in a high-level language that is easy to learn and use, making it ideal for rapid prototyping, educational purposes, and hobbyist projects.
Its embedded Web-Based Development environment offers a unique web interface for writing, editing, and executing code directly from a web browser, eliminating the need for a separate development environment.
This chapter guides you through the initial setup and explains how to install Annex RDS on your ESP32 module.
1.1 What is Annex RDS?
Annex RDS (Rapid Development Suite) is a versatile firmware designed specifically for the ESP32 platform, supporting all ESP32 devices, including single and dual-core modules like the ESP32, ESP32-S2, ESP32-S3, and ESP32-C3. While a version also exists for the ESP8266, it is no longer fully supported due to its reduced resources.
Annex RDS offers a simplified environment for developing applications using BASIC scripting, removing the complexity of traditional microcontroller programming. It takes full advantage of the powerful hardware architecture of the ESP32, utilizing both cores and available RAM. For modules equipped with PSRAM memory extensions, Annex RDS can also make up to 8 MBytes of additional RAM available for users.
1.2 Key Features of Annex RDS
  • Web-Based IDE: Program and debug directly through your web browser, even from a phone or tablet, without any additional utility.
  • Ease of Use: Annex RDS uses a syntax similar to Visual BASIC, making it accessible to beginners and familiar to experienced developers.
  • Real-Time Scripting: Scripts can be written and executed in real time, allowing for quick iterations and testing.
  • Lightweight and Efficient: The interpreter is optimized for the limited resources of embedded devices, ensuring good performance.
  • Multitasking: Supports multiple asynchronous tasks and background activities, like running an MP3 music player while running the main scripts.
  • Device Management: Configures and controls hardware modules such as GPIOs, I2C, SPI, PWM, and more.
  • File System Support: Supports reading from and writing to both internal and external storage (e.g., SD cards).
  • Networking Support: Handles WiFi, MQTT, HTTP, UDP, and more for IoT applications.
  • Automatic Driver Inclusion: Supports many external devices without requiring drivers, as they are already included in the firmware. The list of supported devices is extensive, including temperature sensors, displays, IMUs, and much more.
  • Script Libraries and Multi-File Editing: Allows the creation and inclusion of script libraries, and the ability to edit multiple files directly within the internal IDE for more complex projects.
1.3 Supported Functionalities
Annex RDS provides a wide range of functionalities to support complex projects:
  • Internal IDE: Includes syntax highlighting, context-sensitive help, and a programmable web server with a file server. It supports creating script libraries and editing multiple files for organizing large projects.
  • Over-The-Air (OTA) Updates: Enables firmware updates without needing a physical connection.
  • Async Events and Interrupts: Supports events like timers, web access, H/W events, and more.
  • Debugging Tools: Includes breakpoints, immediate command execution, variable display, and single-step execution.
  • Advanced Data Handling: Supports floating-point and string variables, multi-dimensional arrays, and user-defined subroutines.
  • I/O Control: Access any available I/O pin for input/output, PWM, and Servo controls.
  • Networking Protocols: Supports TCP (HTTP), UDP, SMTP (SSL), AJAX (synchronous and asynchronous), ESP-NOW, MQTT, MODBUS, FTP, BLE, Telegram, and RJ45 wired Ethernet (using W5500 module).
  • Utility Suite: Includes tools like a Flasher, File Manager, HTML Converter, Backup/Restore utility, Serial Port Monitor, OTA update server, and UDP Console.
  • Media Capabilities: Plays MP3 or WAV files and streams audio using a speaker or an external I2S DAC. It also offers text-to-speech capabilities.
  • Regular Expressions: Supports regex for advanced string processing.
1.4 Supported Devices and Modules
Annex RDS natively supports a wide range of devices with dedicated commands and functions, including but not limited to:
  • Temperature/Humidity Sensors: DHT11, DHT21, DHT22, DS18B20
  • Displays:
    • LCD (HD44780 with I2C), ST7920
    • OLED (SSD1306, SH1106)
    • TFT (ILI9341, ILI9163, ST7735, ST7796, ILI9481, ILI9486, ILI9488, ILI7789, SSD1351, GC9A01)
    • Matrix Displays: HUB75
    • 7-Segment Displays: TM1637, TM1638, MAX7219
    • LED Displays: Neopixel WS2812 strips and matrices
  • Audio Modules: VS1053B (for MP3 playback and audio processing)
  • PWM/SERVO Control: PCA9685 module
  • Infrared Communication: Supports various RC protocols for transmission and reception
  • Real-Time Clock (RTC): DS1307, DS3231 modules
  • Ultrasonic Sensors: HC-SR04 for distance measurement
  • Orientation and Motion Sensors: BNO055, MPU9250/MPU6500, MPU6886
  • Environmental Sensors: BME280, BME680, HDC1080, CCS811, APDS9960
  • Ethernet: W5500 RJ45 wired Ethernet interface
  • Distance Sensors: VL53L0X TOF (Time Of Flight) sensor
  • RFID Readers: MFRC522
  • Weight Measurement: HX711 module
  • Clock Generators: SI5351 module
  • Audio: Any compatible I2S DAC
  • LoRa Communication: SX127x modules
  • Motor Control: Stepper motors
  • Video Output: VGA output for ESP32-S3, RGB TFT output for ESP32-S3
1.5 Advantages of Using Annex RDS
  • Ease of Use: Annex RDS simplifies programming through a web interface, making it accessible from any device.
  • Hardware Optimization: It fully utilizes the dual-core architecture and available RAM of the ESP32, including PSRAM extensions.
  • Extensive Device Support: Built-in support for many external devices without the need for additional drivers.
  • Versatile Communication: Supports a wide range of communication protocols, from HTTP to BLE, making it suitable for various IoT applications.
  • Script Management: Facilitates code organization through script libraries and multi-file editing within the internal IDE.
1.6 Use Cases for Annex RDS
  • Prototyping IoT Devices: Quickly develop and test Internet of Things (IoT) applications.
  • Education: Introduce programming concepts to beginners in a simplified environment.
  • Hobby Projects: Create interactive gadgets, home automation systems, and more.
  • Remote Monitoring and Control: Develop applications that require real-time data acquisition and control over the network.
1.7 Getting Started with Annex RDS
To begin using Annex RDS, you need to flash the firmware onto your ESP32 module. The following section provides detailed steps on how to do this, including instructions for using the Online Flasher.
1.7.1 Flashing the Firmware
  1. Visit the Online Flasher: Go to [Local Link Removed for Guests].
  2. Connect to the Device:
    • Click "Connect" to establish a connection.
    • Choose the appropriate port from the list and confirm your selection.
    • The default speed is set to 115200, which is optimal for most devices. You can try increasing this to reduce flashing time, but if an error occurs, reduce the speed back to 115200.
    • For USB devices, leave the speed at its default value.
    • If you have trouble connecting, manually put the module in 'flash mode' (usually by holding down the boot button and pressing the reset button).
  3. Auto-Detect Flash Size:
    • After connecting, the appropriate flash size is automatically detected and set.
    • You can change and force another value if needed.
  4. Select Firmware:
    • Click "Select Firmware" and choose from the available versions.
  5. Choose Firmware Version:
    • Select your desired firmware version and click "Select" to confirm.
  6. Select Partitions:
    • After selecting the firmware, a table will display different partitions. By default, only the firmware partition is selected.
    • For the initial flash, select all partitions to ensure all components are properly flashed.
  7. Configure the Device:
    • If needed, click "Set Config" to configure settings such as WiFi or IP address. This configuration will override any existing settings.
  8. Finalise Flashing:
    • Review your selections and click "Program" to initiate the flashing process. Progress bars will indicate the process.
    • Upon completion, a "Flash process completed!" message will appear, and the module will automatically connect to the console, with the startup message becoming visible.
  9. Power Cycle the ESP32:
    • Disconnect and reconnect the ESP32 to your computer to complete the restart of the module.
1.7.2 Connect to the Annex RDS Web Interface
After flashing the firmware, there are several ways to connect to the Annex RDS web interface:
  • Static IP Assignment:
    • If you have set a specific WiFi name (SSID) and an IP address in the configuration page, the module will start in STA mode (connecting to your local Wi-Fi network). The module will then be accessible at the IP address you configured. Simply open a web browser and go to

      Code: [Local Link Removed for Guests]

      http://yourip
      .
  • Dynamic IP Assignment from Router:
    • If only the WiFi name (SSID) is set (without a specific IP address), the module will connect to your local network and receive an IP address from the router. You must check the console to find the IP address assigned by the router. Simply open a web browser and go to

      Code: [Local Link Removed for Guests]

      http://the_ip_given
      .
  • Default AP Mode:
    • If no settings are configured on the configuration page, the module will start in AP mode with a Wi-Fi network named ESPaa:bb:cc:dd
      , where

      Code: [Local Link Removed for Guests]

      aa:bb:cc:dd
      represents the module's MAC address. In this case:
    • Connect to the Wi-Fi Network:
      • On your computer or device, search for available Wi-Fi networks and connect to the

        Code: [Local Link Removed for Guests]

        ESPaa:bb:cc:dd
        network (no password is required).
    • Access the Web Interface:
      • Open a web browser and go to

        Code: [Local Link Removed for Guests]

        http://192.168.4.1
        .
1.7 Running Your First Annex RDS Program
Now that you have set up the ESP32 module, let's run your first program using Annex RDS.
1.7.1 Writing a Simple "Hello World" Program:
  1. Open the Web Interface:
  2. Create a New Script:
    • In the web interface, click on the "Editor" tab to open the code editor.
  3. Enter the Following Code:

    Code: [Local Link Removed for Guests]

    PRINT "Hello, World!"
  4. Save the Script:
    • Click the "Save" button, and give your script a name e.g.,

      Code: [Local Link Removed for Guests]

      hello.bas
  5. Run the Script:
    • Click the "Run" button to execute the script. You should see "Hello, World!" displayed in the output console.
1.7.2 Understanding the Code:
  • Code: [Local Link Removed for Guests]

    PRINT "Hello, World!"
    : This command prints the text "Hello, World!" to the output console. It’s the most basic command in Annex RDS, similar to how it works in other BASIC dialects.
1.7.3 Modifying the Program:
Let's modify the program to make it more interactive:

Code: [Local Link Removed for Guests]

A = 123
WLOG "The value of A is "; A
  • Code: [Local Link Removed for Guests]

    A = 123
    Sets the value 123 into the variable ‘A’.
  • Code: [Local Link Removed for Guests]

    WLOG
    This command prints the text "The value of A is 123” to the LOG window of the editor page.
  • Save and Run the Modified Script:
    • Click "Save" and then "Run". The message “The Value of A is 123” will be shown inside the LOG window.
1.8 Exploring the Annex RDS Web Interface
The Annex RDS web interface is the primary tool for developing, testing, and debugging your scripts. Here’s a quick overview of its main features:
  • Output: Displays the HTML output of your scripts, is the place where your WEB commands will be sent.
  • Editor: A built-in code editor for writing and modifying BASIC scripts. This is the main page as it contains all the commands to edit, run, and debug your scripts.
  • Config:Configuration options for the ESP32, such as network settings, TFT display, pinout, time zone, and more.
  • File Manager: Allows you to upload, download, and manage files on the ESP32’s internal storage or SD card.
1.9 Conclusion
By the end of this chapter, you should have a basic understanding of what Annex RDS is, how it can be used with the ESP32 platform, and how to set up it for your first programs. In the next chapter, we’ll dive deeper into the Annex RDS interpreter to understand how it handles script execution, memory management, and other core features.
User avatar
Electroguard
Posts: 1094
Joined: Mon Feb 08, 2021 6:22 pm
Has thanked: 373 times
Been thanked: 392 times

Re: First try for a new documentation

Post by Electroguard »

In a word... excellent!

Suggestion: somewhere at the beginning of 1.7 it might be worth emphasising that the user has the choice of sending script output to the serial monitor using PRINT, or by using WLOG instead of print the output can be sent to the Editor log window for quick debugging ... which could explain and clarify those 2 different output examples.
User avatar
cicciocb
Site Admin
Posts: 2781
Joined: Mon Feb 03, 2020 1:15 pm
Location: Toulouse
Has thanked: 592 times
Been thanked: 1989 times
Contact:

Re: First try for a new documentation

Post by cicciocb »

[Local Link Removed for Guests] wrote: [Local Link Removed for Guests]Thu Aug 29, 2024 4:52 pm In a word... excellent!

Suggestion: somewhere at the beginning of 1.7 it might be worth emphasising that the user has the choice of sending script output to the serial monitor using PRINT, or by using WLOG instead of print the output can be sent to the Editor log window for quick debugging ... which could explain and clarify those 2 different output examples.
Thanks Robin, I'll include this detail
BeanieBots
Posts: 521
Joined: Tue Jun 21, 2022 2:17 pm
Location: South coast UK
Has thanked: 291 times
Been thanked: 163 times

Re: First try for a new documentation

Post by BeanieBots »

Indeed, excellent!
It is also noted that you as a 'do-er' does not enjoy the chore of documentation, so.. well done for doing the bit that you don't like.
We really do appreciate all that you do.
User avatar
PeterN
Posts: 641
Joined: Mon Feb 08, 2021 7:56 pm
Location: Krefeld, Germany
Has thanked: 296 times
Been thanked: 357 times
Contact:

Re: First try for a new documentation

Post by PeterN »

This is a very good and helpful step forward!
Please make sure you add a link to it on cicciocb.com as soon as possible, as I have included this link in the link list in the September Elektor article.
So maybe some more newbies and old hands will find their way around this map on the golden Annex path a little better :-)

Thank you!!!
lyizb
Posts: 240
Joined: Fri Feb 12, 2021 8:23 pm
Has thanked: 120 times
Been thanked: 84 times

Re: First try for a new documentation

Post by lyizb »

Outstanding. Hope Annex begins to reach the wider audience that it deserves.
rmsta
Posts: 46
Joined: Sat Feb 20, 2021 9:36 am
Location: Sindelfingen, Germany
Has thanked: 183 times
Been thanked: 11 times

Re: First try for a new documentation

Post by rmsta »

Great ! I appreciate this so much.
Perhaps you can emphasis that programming through the web interface is possible without the need of a physical connection.
This gives so many advantages, if the device is already integrated somewhere.
Greetings Rainer
User avatar
cicciocb
Site Admin
Posts: 2781
Joined: Mon Feb 03, 2020 1:15 pm
Location: Toulouse
Has thanked: 592 times
Been thanked: 1989 times
Contact:

Re: First try for a new documentation

Post by cicciocb »

Thanks for your feedback, I'll try to include your suggestions
User avatar
PeterN
Posts: 641
Joined: Mon Feb 08, 2021 7:56 pm
Location: Krefeld, Germany
Has thanked: 296 times
Been thanked: 357 times
Contact:

Re: First try for a new documentation

Post by PeterN »

[Local Link Removed for Guests] wrote: [Local Link Removed for Guests]Thu Aug 29, 2024 8:11 pm This is a very good and helpful step forward!
Please make sure you add a link to it on cicciocb.com …
IMG_8520.jpeg

Just discovered at [Local Link Removed for Guests] ! Thanks!
You do not have the required permissions to view the files attached to this post.
User avatar
Electroguard
Posts: 1094
Joined: Mon Feb 08, 2021 6:22 pm
Has thanked: 373 times
Been thanked: 392 times

Re: First try for a new documentation

Post by Electroguard »

Just noticed that the new documentation is using 1.7 twice for different things, so needs a slight numbering adjustment...

1.7 Getting Started with Annex RDS
1.7.1 Flashing the Firmware

1.7 Running Your First Annex RDS Program
1.7.1 Writing a Simple "Hello World" Program:
Post Reply