Lua RTOS is a real-time operating system designed to run on embedded systems, with minimal requirements of FLASH and RAM memory. Currently Lua RTOS is available for ESP32, ESP8266 and PIC32MZ platforms, and can be easilly ported to other 32-bit platforms.

Lua RTOS has a 3-layer design:

1. In the top layer there is a Lua 5.3.4 interpreter which offers to the programmer all the resources provided by the Lua programming language, plus special modules for access the hardware (PIO, ADC, I2C, RTC, etc …), and middleware services provided by Lua RTOS (Lua Threads, LoRa WAN, MQTT, …).
2. In the middle layer there is a Real-Time micro-kernel, powered by FreeRTOS. This is the responsible for that things happen in the expected time.
3. In the bottom layer there is a hardware abstraction layer, which talk directly with the platform hardware.

For porting Lua RTOS to other platforms is only necessary to write the code for the bottom layer, because the top and the middle layer are the same for all platforms.

The Lua RTOS compatible boards can be programmed with The Whitecat IDE in two ways: using the Lua programming language directly, or using a block-based programming language that translates blocks to Lua. No matter if you use Lua or blocks, both forms of programming are made from the same programming environment. The programmer can decide, for example, to made a fast prototype using blocks, then change to Lua, and finally back to blocks.

The Whitecat IDE is available at: https://ide.whitecatboard.org.

In our wiki you have more information about this.

1. Please note you need probably to download and install drivers for your board's USB-TO-SERIAL adapter for Windows and Mac OSX versions. The GNU/Linux version usually doesn't need any drivers. This drivers are required for connect to your board through a serial port connection.

   Board
   WHITECAT ESP32 N1
   ESP32 CORE
   ESP32 THING

1. Install The Whitecat Console. The Whitecat Console is a command line tool that allows the programmer to flash a Lua RTOS compatible board with the last available firmware.

   • Download The Whitecat Console binary for your platform.

     • Ubuntu
     • Mac OS
     • Windows

   • Copy The Whitecat Console binary to a folder accessed by the system path.

     • Ubuntu: sudo cp wcc /usr/bin
     • Mac OS: sudo cp wcc /usr/bib
     • Windows: runas /noprofile /user:Administrator "copy wcc.exe c:\windows\system32"

   • Test that The Whitecat Console binary works well.

     For Ubuntu / Mac OS open a terminal and type:

     $ wcc
     usage: wcc -p port | -ports [-ls path | -down source destination | -up source destination |
     -f | -d]
      
     -ports:        list all available serial ports on your computer
     -p port:       serial port device, for example /dev/tty.SLAB_USBtoUART
     -ls path:      list files present in path
     -down src dst: transfer the source file (board) to destination file (computer)
     -up src dst:   transfer the source file (computer) to destination file (board)
     -f:            flash board with last firmware
     -d:            show debug messages

     For Windows open a "command" window and type wcc.exe

2. Find which serial device is used by your board.

   Open a terminal with your board unplugged.

   $ wcc -ports
   Available serial ports on your computer:
   
   /dev/cu.Bluetooth-Incoming-Port
   /dev/cu.Bluetooth-Modem

   Now plug your board.

   $ wcc -ports
   Available serial ports on your computer:
   
   /dev/cu.Bluetooth-Incoming-Port
   /dev/cu.Bluetooth-Modem
   /dev/cu.SLAB_USBtoUART

   In the above example, board is using /dev/cu.SLAB_USBtoUART serial device. This device will be used in the following steps as parameter value -p.

   For windows use wcc.exe instead of wcc.

3. Flash your board.

   Open a terminal with your board plugged.

   $ wcc -p /dev/cu.SLAB_USBtoUART -f

   If you are flashing the Lua RTOS firmware for first time you will get an error:

   Unknown board model.
   Maybe your firmware is corrupted, or you haven't a valid Lua RTOS firmware installed.
   
   Do you want to install a valid firmware now [y/n])?

   Enter "y" if you want to install a valid firmware:

   Please, enter your board type:
     1: WHITECAT N1
     2: ESP32 CORE BOARD
     3: ESP32 THING
     4: GENERIC
   
   Type: 

   Finally enter your board type and your board will be flashed.

   For windows use wcc.exe instead of wcc.

1. Install ESP32 toolchain for your desktop platform. Please, follow the instructions provided by ESPRESSIF:

   • Windows
   • Mac OS
   • Linux

2. Clone esp-idf repository from ESPRESSIF:

   git clone --recursive https://github.com/espressif/esp-idf.git

3. Clone Lua RTOS repository:

   git clone --recursive https://github.com/whitecatboard/Lua-RTOS-ESP32

4. Setup the build environment:

   Go to Lua-RTOS-ESP32 folder:

   cd Lua-RTOS-ESP32

   Edit the env file and change PATH, IDF_PATH, LIBRARY_PATH, PKG_CONFIG_PATH, CPATH for fit to your installation locations.

   Now do:

   source ./env

5. Set the default configuration for your board:

   Board	Run this command
   WHITECAT ESP32 N1	make SDKCONFIG_DEFAULTS=WHITECAT-ESP32-N1 defconfig
   ESP32 CORE	make SDKCONFIG_DEFAULTS=ESP32-CORE-BOARD defconfig
   ESP32 THING	make SDKCONFIG_DEFAULTS=ESP32-THING defconfig
   GENERIC	make SDKCONFIG_DEFAULTS=GENERIC defconfig

6. Change the default configuration:

   You can change the default configuration doing:

   make menuconfig

   Remember to check the device name for your board's USB-TO-SERIAL adapter under the "Serial flasher config / Default serial port" category.

7. Compile:

   Build Lua RTOS, and flash it to your ESP32 board:

   make flash

   Flash the spiffs file system image to your ESP32 board:

   make flashfs

You can connect to the Lua RTOS console using your favorite terminal emulator program, such as picocom, minicom, hyperterminal, putty, etc ... The connection parameters are:

• speed: 115200 bauds
• data bits: 8
• stop bits: 1
• parity: none
• terminal emulation: VT100

For example, if you use picocom:

picocom --baud 115200 /dev/tty.SLAB_USBtoUART

  /\       /\
 /  \_____/  \
/_____________\
W H I T E C A T

Lua RTOS beta 0.1 build 1479953238 Copyright (C) 2015 - 2017 whitecatboard.org
cpu ESP32 at 240 Mhz
spiffs0 start address at 0x180000, size 512 Kb
spiffs0 mounted
spi2 at pins sdi=012/sdo=013/sck=014/cs=015
sd0 is at spi2, pin cs=015
sd0 type II, size 1943552 kbytes, speed 15 Mhz
sd0a partition type 0b, sector 227, size 1943438 kbytes
fat init file system
fat0 mounted
redirecting console messages to file system ...

Lua RTOS beta 0.1 powered by Lua 5.3.4


Executing /system.lua ...
Executing /autorun.lua ...

/ > 

Lua RTOS is free for you, but funds are required for make it possible. Feel free to donate as little or as much as you wish. Every donation is very much appreciated.