search

RealTimeLogic / MinnowServer

A super small and fast embedded HTTP(S) WebSocket server
https://realtimelogic.com/products/sharkssl/minnow-server/
Other
321 stars 54 forks source link
embedded http iot websocket-server websockets

readme

Minnow Server

Minnow Server, a super small and fast embedded HTTP(S) WebSocket server, lets small microcontrollers with no external memory act as real-time web servers.

The Minnow Server includes porting layers for the following platforms:

Bare metal (no RTOS) event-based porting layers:

Note:

The above-mentioned porting layers are not included with the Minnow Server. Carefully read the instructions below to find out how to download the porting layers. Using ESP8266 or ESP32? Check out the ESP8266 build files and the SharkSSL ESP32 IDE.

Minnow Server: One Of Three WebSocket Servers

The Minnow Server is one of three WebSocket server implementations provided by Real Time Logic.

Minnow Server SPA Reference Example

This repository includes the Minnow Server and the Minnow Server Single Page Application (SPA) Reference Example. The Minnow Server is also included in the SharkSSL Repository and will use a secure (HTTPS) connection when used with SharkSSL, but note that the SharkSSL repository does not include the SPA Reference Example. Check out the SharkSSL IDE if you want to quickly test the Minnow Server Reference Example in secure mode (HTTPS). See the tutorial Beginner's Guide To Secure IoT Communication and X.509 Certificate Managment for details.

The Minnow Server Reference Example is a fully functional example that follows the design guidelines outlined in the tutorial Creating Single-Page Apps with the Minnow Server. Figure 1 shows the HTML5 LED web page provided by this example. The example is designed such that one can use it as a base for developing a professional web-based device management application.

Minnow Server Example

Figure 1: The Single Page HTML5 Based Web Application

The example provides a direct WebSocket server API designed for local Intranet use and an optional IoT connection that enables the WebSocket server running on a private network and protected by a firewall to also be accessible from the Internet. The following figure shows how local and external users can access the same device.

Local or External Access

Figure 2: Access reference example locally or via the Internet

The optional IoT solution enables a device installed on a private network to be accessed from the Internet without having to do any network configurations. The example includes the source code for the online IoT server setup. The online server can easily be installed on any cloud solution, including low-cost Virtual Private Servers. An exciting feature of the IoT version is that it allows the external user to use a secure TLS connection when the Minnow Server is not TLS enabled.

See the tutorial IoT Enabled Embedded Web Server for details.

Compiling the Reference Example

The Minnow Server and the reference example can be compiled for any microcontroller. The Minnow Server includes many RTOS and TCP/IP stacks porting layers. However, a few code sections in the example code are designed to run on a non-RTOS environment and must be modified if you plan on compiling the example "as is" for a microcontroller. The purpose with the reference example is educational, and compiling and running the code on a host computer is the first step. You may compile the code on Windows using the included Visual C++ project file or on Linux/Mac using the included makefile.

In addition to the host build environments, we provide a ready-to-use build environment for FreeRTOS/lwIP ESP8266. The following video shows how to compile and upload the code to the ESP8266. The video also shows how to IoT enable the Minnow Server example. See the embedded.com article How to install a secure embedded Web server on ESP8266 for detailed instructions.

ESP8266 Tutorial

No C code option:

For those interested in exploring a simpler option, we also offer an alternative tutorial that demonstrates how to run the SPA reference example using the Barracuda App Server on an ESP32.

Prerequisites

The Minnow Server has two options for compilation: secure and non-secure. If you want to compile the server in non-secure mode, compile and link it with the porting layer in the SMQ GitHub repository. On the other hand, if you opt for secure mode, compile and link it with the secure porting layer found in the SharkSSL GitHub repository.

  1. Carefully read the Minnow Server SPA tutorial, which provides details on the complete SPA development process.
  2. follow one of the two options below:

Non-secure mode (HTTP)

 git clone https://github.com/RealTimeLogic/MinnowServer.git  
 git clone https://github.com/RealTimeLogic/JSON.git  
 git clone https://github.com/RealTimeLogic/SMQ.git

The Minnow Server reference example uses the JSON and SMQ libraries. The SMQ stack is needed even if you do not plan on IoT enabling the reference example since the Minnow Server uses the SMQ TCP/IP porting layer.

Secure mode (HTTPS)

Please note that the Linux makefile is set up to detect SharkSSL automatically, but if you need to compile it for a different target, you can check the dependencies in the makefile.

git clone https://github.com/RealTimeLogic/MinnowServer.git  
git clone https://github.com/RealTimeLogic/JSON.git  
git clone https://github.com/RealTimeLogic/SharkSSL.git
cd MinnowServer/example/make
make minnow
./minnow

Compile and run for developer mode

Compile the code and start the server. The server will attempt to use the default HTTP port or an alternative port if it cannot open the default port. Run the following command on Linux to open the default port 80: sudo ./minnow

Open your hosts file and add the following entry:

127.0.0.1 device

Drag and drop the main HTML file www/index.html into your browser window. The JavaScript code that is part of the SPA will connect to ws://device. Note that the code assumes the server listens on the default port 80. Make sure the server listens on the default port or edit the JavaScript code and add the port number to the URL.

Log in by using the username 'root' and password 'password'.

Compile and run for release mode

Follow the Minnow Server design guide for how to amalgamate and compress all web resources in the 'www' directory. Make sure to select Gzip compression, so the online service creates the required index.c file. Replace example/index.c with the generated file.

Compile and run the server. You may now load the web interface directly from the server by navigating to http://device.

Running on a host operating system in a command window

When running the server in a command window, the four LEDs can also be controlled from the command line using the keyboard keys 'b' to 'e'. A lowercase letter turns the LED off, and an uppercase letter turns the LED on.

The temperature can be controlled from the command line by pressing the up or down arrow keys.

How to IoT enable the reference example

The Minnow Server reference example can also be accessed from outside the Intranet when the reference example is IoT enabled and an SMQ broker is deployed on the Internet. You do not need to set up an online server if you simply want to test the IoT connectivity. In the following example, we will show how to IoT enable the reference example and have the reference example connect to an SMQ broker running on another computer on your Intranet. The SMQ broker needs another IP address than the one used for the Minnow Server. You can use another computer on your Intranet or run the SMQ broker in a virtual machine (VM).

Online IoT bridge Demo: https://minnow.realtimelogic.com/IoT-Bridge-Demo.html

Copy the "IoT" directory to the computer (or VM) where the SMQ broker will run. Download the Mako Server and unpack the server on the same computer. You need the mako executable and mako.zip. Copy those two files to the IoT directory. You should have mako (Win: mako.exe), mako.zip, and the directory www in the IoT directory. The 'www' directory contains the server-side app that sets up the SMQ broker. You also need a copy of the Minnow Server application in the IoT/www directory. Copy everything from 'www' (the Minnow Server application) to IoT/www and rename IoT/www/index.html to IoT/www/device.htmls.

Open device.htmls (The SPA index.html copy) in an editor and add the following line, just below the list of included JavaScript files:

Start the Mako Server as follows:

mako -l::www (on Linux: ./mako -l::www)

The Mako Server prints the port numbers used in the console. We recommend making sure the Mako Server uses the default HTTP port 80. If not, you will have to change the URL in the Minnow Server reference example by opening example/main.c and by changing the SMQ_URL. Change the URL to the following: portno is the port number the Mako Server is listening on.

define SMQ_URL SMQ_PROTOCOL SMQ_DOMAIN " :portno/minnow-smq.lsp?device="

Open your hosts file and add the following entry:

IP-ADDR MakoServer

Where IP-ADDR is the IP address of the computer or VM running the Mako Server.

Alternatively, open example/main.c and search for SMQ_DOMAIN. Change the domain "MakoServer" to the computer's IP address running the Mako Server.

Open example/main.c and add the following at the top of the file, just below the initial comment:

define USE_SMQ

Compile and run the reference example.

Use a browser and navigate to http://MakoServer. The main page shows a list of connected devices. You should see the one device and you may click the link to manage the device via the SMQ broker.

Installing the SMQ Broker on an Online VPS or Cloud Server

Follow the Setting up an Online SMQ IoT Broker tutorial. Replace the server side app in this tutorial with the content of IoT/www.

Files

Minnow Server

Example C code

Single Page Application (SPA)

IoT Server Side Code (Mako Server App)

Embedded Web Server Considerations

Consider reading the following tutorials as they may save you from serious problems down the road: