bhanditz / sming

Sming - Open Source framework for high efficiency native ESP8266 development

Sming

Sming - Open Source framework for high efficiency WiFi SoC ESP8266 native development with C++ language.

Summary

• Fast & user friendly development
• Work with GPIO in Arduino style
• High effective in performance and memory usage (this is native firmware!)
• Compatible with standard Arduino libraries - use any popular hardware in few lines of code
• rBoot OTA firmware updating
• Built-in file system: spiffs
• Built-in powerful network and wireless modules
• Built-in JSON library: ArduinoJson
• HTTP, AJAX, WebSockets support
• MQTT protocol based on libemqtt
• Powerful SmtpClient with support for STARTTLS, PIPELINE, PLAIN and CRAM-MD5 authentication, sending attachments and more.
• Networking based on LWIP stack
• Simple and powerful hardware API wrappers
• Crash handlers for analyzing/handling system restarts due to fatal errors or WDT resets.
• SSL support based on axTLS 2.1+ with Lwirax.
• Out of the box support for HTTP, MQTT and Websocket client connections over SSL.
• Out of the box support for OTA over HTTPS.
• SNI and Maximum Fragment Length SSL support.
• PWM support based on Stefan Bruens PWM
• Optional custom heap allocation based on Umm Malloc
• Based on Espressif NONOS SDK. Tested with versions 1.4, 1.5 and 2.0.

Compatibility

OS/SDK	Linux	Mac OS X	Windows	FreeBSD-current
UDK (v1.5)	n/a	n/a		n/a
esp-alt-sdk (v1.4, v1.5)	☀️	☀️	☀️	☀️
esp-open-sdk (v1.4, v1.5, v2.0)	☀️	☀️	n/a	n/a

OS = Operating System SDK = Software Development Kit n/a = The selected SDK is not available on that OS

Latest Stable Release

• Sming V3.5.2

Getting started

• Windows
• Linux
• MacOS
• Docker

Additional needed software

• ESPtool2 esptool2

Optional features

There are multiple custom features that can be enabled by default. For example: SSL support, custom LWIP, open PWM, custom heap allocation, more verbose debugging, etc. Click here to see the details

• Custom LWIP: (default: ON) By default we are using custom compiled LWIP stack instead of the binary one provided from Espressif. This is increasing the free memory and decreasing the space on the flash. All espconn_* functions are turned off by default. If your application requires the use of some of the espconn_* functions then add the ENABLE_ESPCONN=1 directive. See Makefile-user.mk from the Basic_SmartConfig application for examples. If you would like to use the binary LWIP then you should turn off the custom LWIP compilation by providing ENABLE_CUSTOM_LWIP=0.
• LWIP 2: (default: OFF) LWIP 2 stands for LightWeight IP stack, version 2. In order to enable that feature you should (re)compile the Sming library AND your application using the following directive ENABLE_CUSTOM_LWIP=2. LWIP v2 does not have support for espconn_* functions. This feature is still experimental which means that we still do not recommend it in production.
• SSL support: (default: OFF) The SSL support is not built-in by default to conserve resources. If you want to enable it then take a look at the Readme in the Basic_Ssl samples.
• Custom PWM: (default: ON) If you don't want to use the open PWM implementation then compile your application with ENABLE_CUSTOM_PWM=0. There is no need to recompile the Sming library.
• WPS: (default: OFF) The WPS support (Wi-Fi Protected Setup) is not activated by default to preserve resources. To enable WPS, use the switch ENABLE_WPS=1 for compiling Sming.
• Custom serial baud rate: (default: OFF) The default serial baud rate is 115200. If you want to change it to a higher baud rate you can recompile Sming and your application changing the COM_SPEED_SERIAL directive. For example COM_SPEED_SERIAL=921600.
• Custom heap allocation: (default: OFF) If your application is experiencing heap fragmentation then you can try the umm_malloc heap allocation. To enable it compile Sming with ENABLE_CUSTOM_HEAP=1. In order to use it in your sample/application make sure to compile the sample with ENABLE_CUSTOM_HEAP=1. Do not enable custom heap allocation and -mforce-l32 compiler flag at the same time.
• Debug information log level and format: There are four debug levels: debug=3, info=2, warn=1, error=0. Using DEBUG_VERBOSE_LEVEL you can set the desired level (0-3). For example DEBUG_VERBOSE_LEVEL=2 will show only info messages and above. Another make directive is DEBUG_PRINT_FILENAME_AND_LINE=1 which enables printing the filename and line number of every debug line. This will require extra space on flash. Note: you can compile the Sming library with a set of debug directives and your project with another settings, this way you can control debugging separately for Sming and your application code.
• Debug information for custom LWIP: If you use custom LWIP (see above) some debug information will be printed for critical errors and situations. You can enable debug information printing altogether using ENABLE_LWIPDEBUG=1. To increase debugging for certain areas you can modify debug options in third-party/esp-open-lwip/include/lwipopts.h.
• Interactive debugging on the device: (default: OFF) In order to be able to debug live directly on the ESP8266 microcontroller you should re-compile your application and the Sming library with ENABLE_GDB=1 directive. See Basic_Debug sample for more details.
• CommandExecutor feature: (default: ON) This feature enables execution of certain commands by registering token handlers for text received via serial, websocket or telnet connection. If this feature is not used additional RAM/Flash can be obtained by setting ENABLE_CMD_EXECUTOR=0. This will save ~1KB RAM and ~3KB of flash memory.
• SDK 2.1.0+: (default: OFF) In order to use SDK 2.1 you should set one environment variable before (re)compiling Sming AND applications based on it. The variable is SDK_BASE and it should point to $SMING_HOME/third-party/ESP8266_NONOS_SDK.

For Windows you need to do:

set SDK_BASE %SMING_HOME%//third-party/ESP8266_NONOS_SDK

For Linux(bash) you need to do:

export SDK_BASE="$SMING_HOME/third-party/ESP8266_NONOS_SDK"

Read the comments from this URL for known issues. This feature is still experimental which means that we still do not recommend it in production.

Compilation and flashing

See the getting started page for your respective operating system.

You can find more information about compilation and flashing process by reading esp8266.com forum discussion thread. Official ESP8266 documentation can be found in the Espressif website.

Examples

More information at Wiki Examples page.

Simple GPIO input/output

#define LED_PIN 2 // GPIO2
...
pinMode(LED_PIN, OUTPUT);
digitalWrite(LED_PIN, HIGH);

Connect to WiFi and start Serial communication

Serial.begin(9600);
Serial.println("Hello Sming! Let's do smart things.");

WifiStation.enable(true);
WifiStation.config("LOCAL-NETWORK", "123456789087"); // Put you SSID and Password here

Read DHT22 sensor

#include <Libraries/DHTesp/DHTesp.h> // This is just a popular Arduino library!

#define DHT_PIN 0 // GPIO0
DHTesp dht;

void init()
{
  dht.setup(DHT_PIN, DHTesp::DHT22);

  float h = dht.getHumidity();
  float t = dht.getTemperature();
}

Take a look at the code of the Humidity_DHT22 sample.

HTTP client

HttpClient thingSpeak;
...
thingSpeak.downloadString("http://api.thingspeak.com/update?key=XXXXXXX&field1=" + String(sensorValue), onDataSent);

void onDataSent(HttpClient& client, bool successful)
{
  if (successful)
    Serial.println("Successful!");
  else
    Serial.println("Failed");
}

For more examples take a look at the HttpClient, HttpClient_Instapush and HttpClient_ThingSpeak samples.

OTA application update based on rBoot

void OtaUpdate() {

	uint8 slot;
	rboot_config bootconf;

	Serial.println("Updating...");

	// need a clean object, otherwise if run before and failed will not run again
	if (otaUpdater) delete otaUpdater;
	otaUpdater = new rBootHttpUpdate();

	// select rom slot to flash
	bootconf = rboot_get_config();
	slot = bootconf.current_rom;
	if (slot == 0) slot = 1; else slot = 0;

	// flash rom to position indicated in the rBoot config rom table
	otaUpdater->addItem(bootconf.roms[slot], ROM_0_URL);

	// and/or set a callback (called on failure or success without switching requested)
	otaUpdater->setCallback(OtaUpdate_CallBack);

	// start update
	otaUpdater->start();
}

Embedded HTTP WebServer

server.listen(80);
server.addPath("/", onIndex);
server.addPath("/hello", onHello);
server.setDefaultHandler(onFile);

Serial.println("=== WEB SERVER STARTED ===");
Serial.println(WifiStation.getIP());

...

void onIndex(HttpRequest &request, HttpResponse &response)
{
  TemplateFileStream *tmpl = new TemplateFileStream("index.html");
  auto &vars = tmpl->variables();
  vars["counter"] = String(counter);
  vars["IP"] = WifiStation.getIP().toString();
  vars["MAC"] = WifiStation.getMAC();
  response.sendTemplate(tmpl);
}

void onFile(HttpRequest &request, HttpResponse &response)
{
  String file = request.getPath();
  if (file[0] == '/')
    file = file.substring(1);

  response.setCache(86400, true);
  response.sendFile(file);
}

SmtpClient for sending emails

SmtpClient emailClient;

emailClient.connect(URL("smtp://user:[email protected]:25"));

MailMessage* mail = new MailMessage();
mail->from = "developers@sming";
mail->to = "iot-developers@world";
mail->subject = "Greetings from Sming";
mail->setBody("Hello");

FileStream* file= new FileStream("image.png");
mail->addAttachment(file);

emailClient.onMessageSent(onMailSent);
emailClient.send(mail);

...

int onMailSent(SmtpClient& client, int code, char* status)
{
    MailMessage* mail = client.getCurrentMessage();

    ...

    if(!client.countPending()) {
        client.quit();
    }

    return 0;
}

See the SmtpCient sample for details.

Documentation

A complete documentation can be created by running the command below. This requires doxygen to be installed on your system.

cd $SMING_HOME
make docs

The newly generated documentation will be located under Sming/docs/api