Setup Embedis: a WWW IoT Keystore

Embedis, HTTP/Web, & Telnet servers for the ESP8266

Embedis is a key/value database for embedded projects. The Embedis database is persistent, and can be used across multiple projects to configure your program settings for the specific hardware and network configuration that you are using. It can be used to get/set keys in the Embedis database, such as the the Wi-Fi SSID and Passphrase. You no longer need to embed that data into your program!

Now, you don't need to recompile your program and reflash your device in order to change the device settings anymore. If your ESP8266 Wi-Fi doesn't connect, it reverts to an Access Point with a Web Server to allow you to change the configuration settings and join another Wi-Fi network.

We think that this is a much better mechanism for storing settings between projects. Once you start using Embedis for your projects, you'll see how quick and easy it is to move and reconfigure your devices without needing to recompile and reflash your device firmware just to change a configuration setting.

Now settings can be changed "on-the-fly" with just a web browser! (Some settings changes however, will require a restart/reboot to take effect.)

This example Embedis Arduino IDE sketch for the ESP8266 platform, is used to provide three server applications, namely:

• Embedis Serial Command Line Interface

• Embedis Web Based Command Line Interface on Port 80

• Embedis Telnet Based Command Line Interface on Port 23

To install Embedis in the Arduino IDE, please see the Detailed Install Directions. Embedis is installed using the Arduino Library Manager, from the top menu bar: Sketch -> Include Library -> Manage Libraries -> Embedis

You will also need the ESP8266 tools and ESP8266 sketch data download utility installed with Arduino IDE 1.6.7 or later. For more information, please follow the board manager install directions at esp8266/Arduino.

Embedis Reserved Keys

Embedis generally doesn't care what you name your keys in the dictionary, but we have reserved a few of the more common key names for the usual suspects:

• platform: the name of the platform (e.g. ESP8266, etc.)

• board: the name of the specific board (e.g. Adafruit Huzzah, etc.)

• led_pin: the pin number of the on board LED (default 13)

• wifi_mode: AP (access point) or STA (station - connect to a gateway)

• wifi_ssid: yourSSID (SSID of the Gateway)

• wifi_passwd: yourPASSWORD (Password of the Gateway)

• ap_ssid: Access Point Mode SSID (Local Access Point SSID)

• ap_passwd: Access Point Mode Password (Local Access Point Password)

• login_name: User Name (HTTP/Telnet User Name)

• login_passwd: User Password (HTTP/Telnet Password)

• hostname: Unique Host Name for this Device

• mqtt_server: MQTT Server Name/Address

• mqtt_serverport: MQTT Server Port Number (1883/8883)

• mqtt_name: MQTT User Name

• mqtt_key: MQTT Server Key

SECURITY CAUTION: (WARNING!)

These examples demonstrate only simple authentication methods. These are not intended to be secure, they are teaching examples only.

The authentication scheme used here is very, very simple, where the default device password is a lowercase base64 function of that devices access point Media Access Control, or Ethernet Hardware Address.

The default device password will be printed out on the Serial Monitor during startup, and is unique for each device. This is very important in a classroom situation to keep each student from (accidentally) accessing/changing their neighbors device, and being able to operate a large number of Wi-Fi devices in close proximity.

It is not intended for use in a production environment, where we suggest that encrypted keys and values be used, however that is beyond of the scope of this example. Embedis itself is transparent, so a more secure implementation would encrypt the values (and even the keys themselves) prior to calling Embedis. In this example, all of the keys and values are in unencrypted plain-text, for demonstration, teaching, and debugging purposes.

Connecting to the Embedis Server as an Access Point

When you first build and download the Embedis_Servers project, for most people the people, the internal EEPROM on the platform will be blank, so the Embedis Server will default to Access Point Mode.

This screen capture of the Serial Monitor displays the startup messages :

Now, connect the Wi-Fi of your computer to the ESP8266 device WiFi, in this example screenshot, it would be the AP_SSID - ESP8266:1A:FE:34:9B:64:CC, but yours will be uniquely based on your MAC address.

Once your computers Wi-Fi is connected to the ESP8266 device WiFi (operating as an Access Point), then you can open a web browser on your computer and connect to the Embedis Web Server at the address http://192.168.4.1

If you type a command into the text box, (you can get a list with "commands"), you will be prompted with an authentication popup, shown below :

Enter the HTTP Server Authentication credentials listed for your device, from the Serial Monitor during startup. Remember that each device will be unique, so make sure to use the specific credentials for your device. Once you have correctly entered the User Name and Password, you will have access to the Embedis Server.

Setting Up WiFi

Now you can begin to enter your own keys into the database using the "set" command, and those keys will be written into the on-board EEPROM memory. If you want to get a listing of the keys that are already in the memory, use the "keys" command:

In the example above, the database contains the three keys necessary to connect to an external Wi-Fi Router or Gateway, namely:

• wifi_mode: needs to be set to "STA" for station mode

• wifi_ssid: the SSID of the external Wi-Fi router

• wifi_passwd: the Password of the external Wi-Fi router

You can change these using the "Set" command, as shown below:

Now, you will need to reboot/reset the ESP8266, so press the reset button. The Serial Monitor will then display the log of the startup and connection to the external router. You can also subscribe to even more detailed logs using the "subscribe log" command.

In the above screenshot, the ESP8266 connected to "skynet" with a DHCP assigned address of http://192.168.3.120, however, check your specific Serial Monitor output, as the address is dynamically assigned in most cases. Make sure that your computer, tablet, or phone is connected to the same external network (It might still be connected to the ESP8266 itself as an Access Point)!

Connecting to Embedis from the Network

Now you can access the Embedis Server on your network at it's DHCP assigned address, and you will be required to authenticate (again) using your login/password before the Embedis Server will process your commands:

That is really all there is to it, now you have a template project for storing and modifying your project settings using Embedis, either using the Web Browser, or the Serial Monitor (try typing commands in the Serial Monitor as well), or using Telnet at port 23 (we'll cover that in an upcoming project).

Note that there are also some basic commands for controlling I/O, like pinMode, DigitalRead, DigitalWrite, and others. Now you can toggle pins on your project simply by typing commands into the web browser. And Embedis is extensible, so you can add your own commands with just a few lines of code.

Happy Hacking!

Troubleshooting

• This project uses both the ESP8266 Emulated EEPROM and the SPIFFS File System. The first mistake most people make is not uploading the File System using the "Tools -> ESP8266 Sketch Data Upload" command. This is a separate step from uploading the sketch (I.e. the program) itself. The Web Servers file system resides on the SPIFFS File System, and it won't work without it. Remember to close the Serial Monitor Window BEFORE doing the "Tools -> ESP8266 Sketch Data Upload" command, or the upload will fail.

• The ESP8266 doesn't always reset properly after upload, so sometimes a manual reset is required.

• Make sure that your computer, tablet, or phone Wi-Fi are connected to the ESP8266 itself, when the ESP8266 is operating as an Access Point (wifi_mode="AP").

• Make sure that your computer, tablet, or phone are connected to the same External Wi-Fi Router as the ESP8266, when the ESP8266 is operating in Station Mode (wifi_mode="STA").