https://mosquitto.org/download/

• Home
 
• Downloads
 
• Documentation
 
• Bugs / Support
 
• 

Mosquitto

An Open Source MQTT v3.1/v3.1.1 Broker

Downloads

Donation

Developing Mosquitto takes a not insignificant amount of time and effort. If you find it useful, please consider making a donation.

Source

• mosquitto-1.4.11.tar.gz (319kB) (GPG signature)
• mosquitto-1.4.11.tar.gz (via Eclipse)
• Git source code repository (github.com)

Older downloads are available at http://mosquitto.org/files/

The deprecated javascript/websockets client is available as:

• http://mosquitto.org/js/mosquitto-1.1.js
• http://mosquitto.org/js/mosquitto-1.1.min.js

Please consider using the Paho Javascript client instead.

Binary Installation

Windows

• mosquitto-1.4.11-install-win32.exe (~200 kB) (Native build, Windows Vista and up, built with Visual Studio Community 2013)
• mosquitto-1.4.11-install-cygwin.exe (~200 kB) (Cygwin build, Windows XP and up)

See the readme-windows.txt after installing for Windows specific details and dependencies.

Mac

Mosquitto can be installed from the homebrew project. See  http://brew.sh/ and then use “brew install mosquitto”

Arch Linux

• https://aur.archlinux.org/packages/mosquitto/

CentOS

Download the repository config file for your CentOS version from below and copy it to /etc/yum.repos.d/ You’ll now be able to install and keep mosquitto up to date using the normal package management tools.

The available packages are: mosquitto, mosquitto-clients, libmosquitto1, libmosquitto-devel, libmosquittopp1, libmosquittopp-devel, python-mosquitto.

• CentOS 7
• CentOS 6

Debian

• Mosquitto is now in Debian proper. There will be a short delay between a new release and it appearing in Debian as part of the normal Debian procedures.
• There are also Debian repositories provided by the mosquitto project, as described at http://mosquitto.org/2013/01/mosquitto-debian-repository/

Fedora

Mosquitto is now available from Fedora directly. Use “yum install mosquitto”, or search for “mosquitto” to find the related packages.

It is also still available as a binary provided by the mosquitto project: download the repository config file for your Fedora version from below and copy it to /etc/yum.repos.d/ You’ll now be able to install and keep mosquitto up to date using the normal package management tools.

The available packages are: mosquitto, mosquitto-clients, libmosquitto1, libmosquitto-devel, libmosquittopp1, libmosquittopp-devel, python-mosquitto.

• Fedora 22
• Fedora 21

FreeBSD

Mosquitto is available for FreeBSD: http://www.freshports.org/net/mosquitto/

Gentoo

Use “emerge mosquitto”

Mandriva

(no longer supported by the opensuse build service)

openSUSE

Download the repository config file for your openSUSE version from below and copy it to /etc/zypp/repos.d/ You’ll now be able to install and keep mosquitto up to date using the normal package management tools.

The available packages are: mosquitto, mosquitto-clients, libmosquitto1, libmosquitto-devel, libmosquittopp1, libmosquittopp-devel, python-mosquitto.

• openSUSE 13.2
• openSUSE 13.1

OpenWrt

If you’re using a trunk snapshot use “opkg update; opkg install mosquitto”

Karl Palsson maintains a set of feeds that may be more up to date than the current OpenWrt version:

• https://github.com/remakeelectric/owrt_pub_feeds

Raspberry Pi

Mosquitto is available through the main repository.

There are also Debian repositories provided by the mosquitto project, as described at http://mosquitto.org/2013/01/mosquitto-debian-repository/.

These packages are sponsored by PCextreme B.V., who are providing Raspberry Pi hosting for building the packages.

Redhat Enterprise Linux

Download the repository config file for your RHEL version from below and copy it to /etc/yum.repos.d/ You’ll now be able to install and keep mosquitto up to date using the normal package management tools.

The available packages are: mosquitto, mosquitto-clients, libmosquitto1, libmosquitto-devel, libmosquittopp1, libmosquittopp-devel, python-mosquitto.

• RHEL 7
• RHEL 6
• RHEL 5

Slackware

Courtesy of Chris Willing – http://www.vislab.uq.edu.au/howto/mqtt/index.html

SUSE Linux Enterprise Server

Add the appropriate repository to your package config from the list below, then install mosquitto from your normal package management tools.

• SLE 11 SP3 – http://download.opensuse.org/repositories/home:/oojah:/mqtt/SLE_11_SP3/
• SLE 11 SP2 – http://download.opensuse.org/repositories/home:/oojah:/mqtt/SLE_11_SP2/
• SLE 10 – http://download.opensuse.org/repositories/home:/oojah:/mqtt/SLE_10_SDK/

Ubuntu

As of version 11.10 Oneiric Ocelot, mosquitto will be in the Ubuntu repositories so you can install as with any other package. If you are on an earlier version of Ubuntu or want a more recent version of mosquitto, add the mosquitto-dev PPA to your repositories list – see the link for details. mosquitto can then be installed from your package manager.

• sudo apt-add-repository ppa:mosquitto-dev/mosquitto-ppa
• sudo apt-get update

If the command “apt-add-repository” is not recognised, it can be installed with:

• sudo apt-get install python-software-properties

Other Linux

Other users – no packages available. Get in touch if you want to help!

QNX

• 0.11.3 in http://mosquitto.org/files/binary/qnx/ – untested, expect no updates.

iPhone

You can use libmosquitto (included in the source download) on the iPhone to build MQTT apps. It compiles as objective-c, or you can use the marquette project which is an objective-c wrapper and example app.

Back to top

Pages

• Bugs / Support
• Documentation
  • Python
• Downloads

Links

• Mosquitto test server
• MQTT community
• mqtt2cosm
• Paho

Donate

If you find mosquitto useful, please consider a donation to help support development and the running of the test server.

Meta

• Log in
• Entries RSS
• Comments RSS
• WordPress.org

Eclipse

Mosquitto is an Eclipse incubating project, click the egg for more details:

Powered by WordPress | Based on theme by Ori Pearl

MQTT簡介

源自於
http://blog.maxkit.com.tw/2014/01/mqtt.html

MQTT(一)簡介

前言

會知道MQTT協定，要先回憶起兩年前，當初想找找Android的Push Notification的解決方案，先是找到了當時GCM的前身C2DM，以為Google已經提供了此服務，測試了一下code也蠻容易上手的，結果發現到他有quota限制，不適合拿來當成產品，因此就放棄它，改找別的解決方案，最後找到了兩種不同的實作方式，一種透過XMPP協定來完成，另一種也就是今天要提到的，透過MQTT來完成。

所以MQTT是什麼？

MQTT的全名為 Message Queuing Telemetry Transport，為IBM和Eurotech共同製定出來的protocol，在MQTT的官網可以看到一開始它對MQTT的介紹：

MQTT is a machine-to-machine (M2M)/"Internet of Things" connectivity protocol. It was designed as an extremely lightweight publish/subscribe messaging transport.

簡單來說，它是為了物聯網而設計的protocol，並且它是透過publish/subscribe的方式來做訊息傳送。由於是為了物聯網而設計的協定，因此它所需要的網路頻寬是很低的，而所需要的硬體資源也是低的。

Publish/Subscribe：

在看MQTT之前，最好要先知道Publish/Subscribe的訊息傳送機制為何，這樣之後在看其協定時，才會更快上手。Publish/Subscribe有三種主要的組成元件，分別為Publisher、Subscriber以及Topic。

Publisher為訊息的來源，它會將訊息發送給Topic，而Subscriber向Topic註冊，表示他們想要接收此Topic的訊息；因此當有某個Publisher對Topic發送訊息時，只要是有對此Topic註冊的Subscriber，都會收到此則訊息。
它們的關係如下圖：

MQTT特性：

了解了Publish/Subscribe的機制之後，讓我們來看看MQTT有哪些特性：

1. Publish/Subscribe的訊息傳送模式，來提供一對多的訊息分配。
2. 使用TCP/IP來提供基本的網路連結。
3. 三種訊息傳送服務的qualities：
   
   • "At most once"，最多一次，訊息遺失或是重複發送的狀況可能會發生；這種quality適合應用在環境感測，不在意資料是否會遺失，因為下一次的資料取樣很快就會被published出來。
   • "At least once"，至少一次，這種quality保證訊息會送達，只是可能會發生重複發送訊息的狀況。
   • "Exactly once"，確定一次，確認訊息只會送到一次。這種quality適合用在計費系統，系統只要有重複收到資料、或是資料遺失狀況發生，就會造成系統錯誤。
4. 由於他的header固定長度為2byte，因此可以減少封包傳送時的額外負載，並減少所需的網路頻寬。
5. 當異常斷線發生時，會使用最後遺囑(Last Will and Testament)的機制，通知各個感興趣的client。

MQTT現況：

MQTT現階段並不是一個標準化的Protocol，還在持續改進中，目前為MQTT V3.1。不過IBM已於2013年已經將它交給OASIS進行標準化了，並且一直以來IBM對此協定採開放、免授權費的方式讓它能夠被散佈，因此相信不久的將來會成為一個主流的Protocol。

而目前支援MQTT的Client API，有Eclipse Phno Project有對MQTT client支援，其支援C、Java、Javascript、C++等等的語言，可說是支援度很高的Project。而目已經在應用MQTT的，最知名的應該就是Facebook Message App了吧，可以參考此篇文章文章。

小結：

上面提到的，低頻寬、低硬體需求的特性，訊息傳遞為Publish/Subscribe的方式，正好可以用來實現Push Notification的機制，並且能達到手持裝置省電的需求，接下來會先從其Protocol開始了解，並用Client Api跑些範例來應用此Protocol。

MQTT Mosquitto 安裝筆記

源自於
http://guang.logdown.com/posts/235550-mqtt-mosquitto-teaching

MQTT Mosquitto 安裝筆記

Mosquitto 是Open Source的MQTT Broker

此篇筆記主要是記錄如何安裝並使用Mosquitto

下載

http://mosquitto.org/download/
選擇自己的OS，這裡將以win7為例 (mosquitto-1.3.2-install-win32.exe)

安裝

Follow Installer，基本上就一路按下一步
安裝完成後，目錄會放在
C:\Program Files(x86)\mosquitto
並且會新增環境變數
MOSQUITTO_DIR指到該目錄

操作

Broker的主程式為mosquitto.exe
操作方法為
mosquitto.exe -v -p port
我會習慣下-v來啟動verbose mode，方便作debug
default port是1883

到這邊為止，已經成功跑起一個MQTT Broker!

另外，在Mosquitto的目錄下還提供了publish/subscribe的程式，可以拿來玩一玩
publish:
mosquitto_pub.exe -h host -p port -q qos -t topic -m message
subscribe:
mosquitto_sub.exe -h host -p port -q qos -t topic

DEMO

1.啟動Broker
2.Subscriber 註冊感興趣的Topic(ex. sensor/temperature)

3.Publisher 發布該Topic的訊息

4.Sbscriber 接收Topic訊息

Down Count

http://community.blynk.cc/t/solved-how-to-countdown/10673/6

#define BLYNK_PRINT Serial    // Comment this out to disable prints and save space
#include <ESP8266WiFi.h>
#include <BlynkSimpleEsp8266.h>
#include <SimpleTimer.h>

SimpleTimer timer;

// You should get Auth Token in the Blynk App.
// Go to the Project Settings (nut icon).
char auth[] = "461366bb2e7d46b7b0a0d4d785da7c3b";
// Your WiFi credentials.
// Set password to "" for open networks.
char ssid[] = "74170287";
char pass[] = "24063173";

int CountdownRemainReset;
int CountdownRemain;
int CountdownTimer;


void CountdownTimerFunction() {
  CountdownRemain--; // remove 1 every second
  CountdownShowFormatted(CountdownRemain);
  if (!CountdownRemain) { // check if CountdownRemain == 0/FALSE/LOW
    timer.disable(CountdownTimer); // if 0 stop timer
    Blynk.virtualWrite(V1, LOW); // reset START/STOP button status
    Blynk.virtualWrite(V0, "TIMER COMPLETE");
    Blynk.virtualWrite(V6, 255); // LED for timer completed
    Blynk.virtualWrite(V5, 0); // Timer LED status light off
  } else {
    Blynk.virtualWrite(V6, 0); // LED for timer completed
  }
}

// Button Widget (Switch Type): Start/Pause Timer
BLYNK_WRITE(V1) {
  if (param.asInt()) {
    if (CountdownRemain) { // check if there is a time set or not
      timer.enable(CountdownTimer);
      Blynk.virtualWrite(V5, 255); // Timer LED status light on
    } else {
      Blynk.virtualWrite(V1, LOW); // if CountdownRemain is set to 0, then dont start hte timer.
      Blynk.virtualWrite(V0, "COUNTDOWN TIME NOT SET"); // if CountdownRemain is set to 0, then tell the user
    }
  } else {
    timer.disable(CountdownTimer);
    Blynk.virtualWrite(V5, 0); // Timer LED status light off
  }
}

// Button Widget (Momentary): Reset Timer
BLYNK_WRITE(V2) {
  CountdownRemain = CountdownRemainReset; // reset to original start time
}

// Slider Widget (60-180): Set Timer (mins)
BLYNK_WRITE(V3) {
  if (timer.isEnabled(CountdownTimer)) { // only update if timer not running
    Blynk.virtualWrite(V3, param.asInt() ); // if running, refuse to let use change slider
  } else {
    CountdownRemainReset = param.asInt() * 60 + 1; // + 1 set the timer to 1:00:00 instead of 00:59:59
    CountdownRemain = param.asInt() * 60;
    CountdownShowFormatted(CountdownRemain);
  }
}

void CountdownShowFormatted(int seconds) {
  long days = 0;
  long hours = 0;
  long mins = 0;
  long secs = 0;
  String secs_o = ":";
  String mins_o = ":";
  String hours_o = ":";
  secs = seconds; // set the seconds remaining
  mins = secs / 60; //convert seconds to minutes
  hours = mins / 60; //convert minutes to hours
  days = hours / 24; //convert hours to days
  secs = secs - (mins * 60); //subtract the coverted seconds to minutes in order to display 59 secs max
  mins = mins - (hours * 60); //subtract the coverted minutes to hours in order to display 59 minutes max
  hours = hours - (days * 24); //subtract the coverted hours to days in order to display 23 hours max
  if (secs < 10) {
    secs_o = ":0";
  }
  if (mins < 10) {
    mins_o = ":0";
  }
  if (hours < 10) {
    hours_o = ":0";
  }
  Blynk.virtualWrite(V0, days + hours_o + hours + mins_o + mins + secs_o + secs +"\r\n");
}


void setup() {
  Serial.begin(9600);
  Blynk.begin(auth, ssid, pass);
  while (Blynk.connect() == false) {}
  CountdownTimer = timer.setInterval(1000, CountdownTimerFunction);
  timer.disable(CountdownTimer); // disable it on boot
}

void loop() {
  Blynk.run();
  timer.run();
}

http://telecnatron.com/articles/Getting-Started-With-The-ESP8266-WIFI-Microcontroller/index.html

http://telecnatron.com/articles/Getting-Started-With-The-ESP8266-WIFI-Microcontroller/index.html

Getting Started With The ESP8266 WIFI Microcontroller

By Stephen Stebbing2015-03-07 02:04:05 2 comments

ESP8266 is a powerful, WIFI enabled, 32-bit microcontroller which is available for just a few dollars. Given its versatility, it is not surprising that it is becoming very popular for InternetOfThings-type application, and will likely continue to do so. It has a strong and helpful community of users behind it, and new applications and tools are being developed very rapidly.

Contents

1. The ESP-01 Module

2. Connecting to the Serial Port

3. Testing the Module: AT Commands

3.1. Initial Test

3.2. Connecting the ESP8266 to an Access Point.

4. Cross Compiler Tools and C SDK Installation.

4.1. xtensa-lx106-elf/

4.2. esp_iot_sdk_v0.9.5

4.3. esptool

4.3.1. Flashing Code to the Device

5. Development Jig

6. NodeMCU Lua Interpreter

6.1. Developing Applications with NodeMCU

6.1.1. luatool: Automating File Uploads

6.1.2. luatool-src: Uploading Lua Code

6.1.3. Development Process

6.1.4. init.lua

6.1.5. Compiling .lua Files to .lc Lua Bytecode

6.1.6. Using the C Preprocessor

7. Conclusion

8. Links and Resources

The difficulty that I had in getting started was that there was no central source for the required information; I ended up spending quite some time searching, trolling through forums, reading source code and various other documentation in order to get up and running, and to glean some idea about how things work, and what is going on in general.

Anwyay, here I will document the various steps that I took to:

• Wire up the hardware
• Test the module with AT commands
• Install the C SDK
• Flash the device
• Set up for development with NodeMCU Lua environment

1. The ESP-01 Module

There are several different modules available, each with different form-factors and with various pin outs. The one we will be using is known as the ESP-01, and makes accessible just enough pins to make it usable, as show here:

Pin	Signal
VCC	3.3V (3.6V Max)
GND	Ground
TXD	UART TX line
RXD	UART RX line
CH_PD	Chip Power Down (Pull high for chip active)
GPIO0	General Purpose I/O 0 *
GPIO1	General Purpose I/O 1 *
RST	Reset (pull LOW to reset)

The device requires a nominal 3.3V supply, but will operate from a signifigantly lower voltage. I have heard reports successful operation at as low as 1.8v, but have not tested this myself.

Note that the device is not 5V tolerant. Level conversion is required when interfacing with 5V devices.

TXD and RXD are the serial transmit and receive lines.

CH_PD is the chip enable line. This should be pulled high.

A low pulse on RST will reset the device.

If GPIO0 is pulled low on startup, the device will enter its bootloader mode whereby FLASH data can be uploaded via the serial port. For normal operation it should be pulled high (or left floating).

If GPIO2 is low on startup, the device will not start. For normal operation, it should be pulled high (or left floating).

If GPI00 or GPIO2 are being used as outputs, care needs to be taken that they are not being pulled low by the circuitry that they are connected to.

2. Connecting to the Serial Port

As mentioned above, the TXD and RXD lines need to be driven with 3.3v logic levels, so a max2323 module (with 3.3v Vcc) can be used to conver theses level to RS232.

Alternatively, if a USB to serial converter is used, it must be one that is capable of 3.3v logic levels, such as the one shown at left which is labeled CP2102. The solder pad marked with the yellow line near top is bridged to set the level to 3.3v.

The TXD and RXD lines need to be crossed. That is, TXD on the USB module nees to be connected to RXD on the ESP8266 module, and RXD to TXD.

Note that the USB to serial converter cannot supply enough current via it’s Vcc pin to operate the ESP8266. A seperate power supply must be used.

3. Testing the Module: AT Commands

The module is supplied with the ‘AT’ firmware which allows it to be controlled via AT commands issued over the serial port (similiar to old modems). The idea being that an Aurdino etc can WIFI-enable itself by issuing commands to the ESP8266, but this seems kind of pointless given that the ESP8266 is a much more powerful processor; by installing custom firmware on the ESP8266, the Aurdino more or less becomes unnecessary.

Anyway, we’ll use AT commands here to connect the ESP8266 to the local WIFI and test that everything it is working.

Connect the modules as shown, and configure your serial terminal program for 115200,N,8,0. (Apparently, some older modules use 9600 baud).

RST pin (not shown on diagram) should also be connected to 3.3V, although I found that things still worked when it was left floating.

For a quick lash up, ‘dupont’ style jumper cables work fine.

3.1. Initial Test

By default, the AT firmware is configured to initialise the ESP8266 as a WIFI access point, and it includes a DHCP server to assign IP numbers to the devices that connect to it.

Listing the local access points shows that the ESP8266 is working as expected, with ssid of ESP_9D915B:

~>sudo iwlist scan | grep ssid -i
                    ESSID:"ESP_9D915B"
                    ESSID:"Motorola"
                    ESSID:"BigPondA26979"
                    ESSID:"Florence"

Using NetworkManager (or whatever you use to connect your PC to an access point) we can connect to the ESP_9D915B access point, and check that an IP number has been assigned, and then we can ping the ESP8266:

~>ifconfig wlan0
wlan0     Link encap:Ethernet  HWaddr 1c:4b:d6:78:6b:8d  
          inet addr:192.168.4.2  Bcast:192.168.4.255  Mask:255.255.255.0
          inet6 addr: fe80::1e4b:d6ff:fe78:6b8d/64 Scope:Link
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:705438 errors:0 dropped:0 overruns:0 frame:0
          TX packets:590920 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000 
          RX bytes:688774640 (688.7 MB)  TX bytes:112196991 (112.1 MB)



~>route -n
Kernel IP routing table
Destination     Gateway         Genmask         Flags Metric Ref    Use Iface
0.0.0.0         192.168.4.1     0.0.0.0         UG    0      0        0 wlan0
192.168.4.0     0.0.0.0         255.255.255.0   U     9      0        0 wlan0

~>ping 192.168.4.2
PING 192.168.4.1 (192.168.4.1) 56(84) bytes of data.
64 bytes from 192.168.4.1: icmp_seq=1 ttl=64 time=0.143 ms

The ESP8266 has IP number 192.168.4.1 and has assigned the PC 192.168.4.2 and all is well.

3.2. Connecting the ESP8266 to an Access Point.

To configure the ESP8266 to connect to a local access point, we use a terminal program (such as minicom) to send AT commands to the ESP8266 via its serial port.

Note that the AT firmware expects lines to be terminated with the two character sequence ‘\r\n’, so you may need to configure the terminal program to automatically append the ‘\n’.

I could not get this to work when using minicom on Linux, but found that typing CTRL-M CTRL-J to end the line was a satisfactory workaround.

If you now type AT followed by ENTER (or CTRL-M CTRL-J) into the terminal program, you should see the ESP8266 respond with an OK prompt.

You can now try some other AT commands:

• AT+RST to reset the device.
• AT+GMR to show the firware versions

The ESP8266 can be configured as a WIFI access-point, a station, or both. To prepare for connection to the local access-point, issue the command AT+CWMODE=3, which sets it to be both. Then, the AT+CWLAP command causes the ESP8266 to list the nearby networks:

+CWLAP:(1,"Motorola",-87,"00:14:a5:c5:46:ec",1)
+CWLAP:(3,"ss.com",-77,"0c:12:68:dd:df:14",11)
+CWLAP:(4,"BigPondA26979",-89,"00:26:44:a2:69:79",11)
+CWLAP:(4,"Florence",-89,"00:1f:f3:c0:08:6a",11)

Which shows the encryption method, the ssid string, the rssi (signal strength) in dBm, the mac address, and the channel number.

Finally, we connect to the local access-point with the command:

@AT+CWJAP="Florence",""@
OK

The LAN runs dhcp, so we check that an IP address has been assigned with AT+CIFSR:

+CIFSR:APIP,"192.168.4.1"
+CIFSR:APMAC,"00:1f:f3:c0:08:6a"
+CIFSR:STAIP,"192.168.0.101"
+CIFSR:STAMAC,"18:fe:34:9d:91:5b"
OK

To set a static IP, use the AT+CIPSTA="192.168.101.108" command. It is unclear on how the gateway and netmask etc are set, but persumably this is possible.

Note that the AT firmware saves the settings in the ESP8266’s flash memory, meaning that configuration is retained after the device is reset.

It is further possible to use other AT commands to configure the ESP8266 to connect to a TCP or UDP host as a client, or to act as a server. See here for the full list of AT commands.

4. Cross Compiler Tools and C SDK Installation.

Espressif, the ESP8266’s manufacturer, provide the source code for the gcc cross-compiler tool chain, and for their C SDK (Note that some parts of the SDK are closed source, and distributed as object code only).

Unfortunately, due to its relative newness and being rapidly changing, installing it all is quite fiddly, error prone, and tedious, but fortunately, pfalcon has come to the rescue and combined everything into his single esp-open-sdk package which can be installed on Linux quite effortlessly. We will be using it here.

First, we need to ensure that the standard GNU development tools are installed. For Ubuntu 14.04:

>sudo apt-get install make unrar autoconf automake libtool gcc g++ gperf \
    flex bison texinfo gawk ncurses-dev libexpat-dev python sed

Create a directory for everything to go in:

>mkdir /usr/local/cross-compile/esp8266
>cd /usr/local/cross-compile/esp8266

Then, download, build and install:

>git clone https://github.com/pfalcon/esp-open-sdk
>make STANDALONE=n

This will take some time, but when it is done everything is installed in the esp-open-sdk subdirectory, which has three important subdirectories: xtensa-lx106-elf, esp_iot_sdk_v0.9.5, and esptool which we will look at now.

4.1. xtensa-lx106-elf/

This contains gcc and the other GNU tool chain utilities. The bin/ directory should be added to the search path, with something like this:

PATH="/usr/local/cross-compile/esp8266/esp-open-sdk/xtensa-lx106-elf/bin:$PATH"

4.2. esp_iot_sdk_v0.9.5

This contains the SDK and the various other bits and pieces required to build user applications:

• As usual, include/ and lib/ subdirectories contain the C header files and the object-code library files.
• PDF documentation for the API is in the document subdirectory.
• examples/at subdirectory contains the source code for the AT firmware that we were using previously. examples/IoT_Demo demonstrates the use of much of the API and the device’s capabilities- very handy to base your code on, especially when first starting out.
• The bin/ subdirectory contains the ESP8266 binary files, ready for uploading to the device. We’ll look closer at these in the next section

4.3. esptool

This contains the esptool.py python utility which is the community-developed tool used for uploading the binaries to the ESP8266’s flash memory, as well as for assembling the binaries from the gcc-generated elf-format files. For ease of access, you can copy esptool.py to /usr/bin/local or somewhere else on the search path.

Note that Espressif provide their own esptool (a binary exe and without the .py extension) which works similiary to esptool.py but is not as fully featured. esp-open-skd has replaced its use with esptool.py. You might come across it if you are compiling third-party applications, so don’t get confused.

4.3.1. Flashing Code to the Device

For practise, we’ll reflash the device with the AT firmware which is in the bin/at subdirectory. First, put the ESP8266 into bootloader mode by pulling GPIO0 line low, and reset, and then:

>cd /usr/local/cross-compile/esp8266/esp-open-sdk/esp_iot_sdk_v0.9.5/bin
>esptool.py write_flash 0x00000 boot_v1.2.bin 0x01000 at/user1.512.new.bin 0x3e000 blank.bin 0x7e000 blank.bin

boot_v1.2.bin is the Espressif SDK and other operating-system like code, and it gets written to the device’s flash starting at address 0×00000; as far as I know, this only has to be reflashed if Espressif release a new version of the SDK for example.

at/user1.512.new.bin is the user application code, being the AT firmware in this case, and it is written starting at address 0×01000. The application code should always be written at this address.

The blank.bin file contains all 0xFF bytes and is the size of one flash sector of 4096 bytes. It is written to the addresses wherein the flash needs to be erased. The 0×7e000 sector is used by the SDK to store it persistent data, and presumably 0×3e000 is used by the AT application.

5. Development Jig

When frequently flashing during development, plugging wires in and out quickly became tedious so I decided to build the little board described here so I could just flick a switch and push reset instead.

The reset line is pulled up gently via the 10k resistor as the capacitor charges, this should prevent any problems with voltage spikes etc when the power is applied. The push button across the capacitor is used to reset the device.

The toggle switch selects between flash mode and normal running mode. To change mode, the switch is set to the appropiate position and then the reset button is pushed.

The 10k pullup and push button on the GPIO2 line isn’t necessary, but might come in handy.

The jig was knocked up quickly on a piece of matrix board using point-to-point wire-wrap-and-solder technique.

The module mounts into two rows of 4-pin female pin-headers set adjacent to each other, which allow for easy insertion and removal.

There is space at right to add adapters for the various other ESP8266 modules.

6. NodeMCU Lua Interpreter

NodeMCU is a Lua interpreter that runs on the ESP8266. It allows for rapid development of simple applications in an Aurdino like manner, and without the overhead of having to get up to speed with the C API. For many small, non-speed critical applications, such as my telnet controlled relay, it would appear to be a good choice. It is currently under constant development, with new features being added frequently.

Installing it is as simple as:

>cd /usr/local/cross-compile/esp8266
>git clone https://github.com/nodemcu/nodemcu-firmware.git
>cd nodemcu-firmware
>make

then, reset the device into flash mode, and:

>cd app
>make flash

then, with serial connected and set to 9600 baud, reset the device and you should be greeted with the lua prompt and you can start typing in commands:

NodeMCU 0.9.5 build 20150213  powered by Lua 5.1.4
lua: cannot open init.lua
> print("hello lua")
hello lua
> > print(node.heap())
21464
>

The node.heap() method shows that there is 21kB available for our Lua programs.

To connect to access point:

>  wifi.setmode(wifi.STATION)
>  wifi.sta.config("Florence","")
> ip = wifi.sta.getip()
> print(ip)
192.168.0.101

Note that the wifi settings stored in the flash memory and are retained across device resets.

See the GitHub readme for lots of code snippets demonstrating NocdeMCU’s features; a rudimentry webserver can be implemented in half a dozen or so lines. The API Documentaion is available also on GitHub.

6.1. Developing Applications with NodeMCU

As, no doubt, can be imagined, when trying to develop an application by constantly typing in lua commands, or trying to cut-and-paste, at the serial console is a very painful experience, but NodeMCU helps us withh its spiffs flash file-system which allows for Lua code to be stored in the files and loaded as required.

A file can be written and then executed with something like:

> file.open("heap.lua", "a+")
> file.write("print(node.heap())\n")
> file.close()
> dofile("heap.lua")
20384
>

6.1.1. luatool: Automating File Uploads

4refr0nt has written the luatool python utility that allows for lua source code files to be rapidly uploaded to the the device. It works by simply encasing the source file’s contents in file.write('') calls which are written to the device’s serial port, just as if you had typed them, but much quicker of course.

>luatool.py --port /dev/ttyUSB0 --src main.lua --dest main.lua --verbose
...
->file.open("main.lua", "w+") -> ok
...
->file.writeline([[ip = wifi.sta.getip()]]) -> ok
->file.writeline([[print(ip))]]) -> ok
...
->file.flush() -> ok
->file.close() -> ok

6.1.2. luatool-src: Uploading Lua Code

I’ve hacked the luatool to allow it to upload Lua source files directly to the interpreter, ie not write it to a file, and just as if you had typed each line. It’s avaliable here.

>luatool-src.py -f test.lua
->function hello(name) -> ok
->print ("hello "+name) -> ok
->end -> ok
--->>> All done <<<---

6.1.3. Development Process

While writing code, I found it easiest to use luatool-src.py to upload the function, class, or whatever that you are currently working on, then, when it is debugged and finished, use luatool to write it as a file to flash, and then repeat until the application is completed.

6.1.4. init.lua

At startup, NodeMCU will automatically call the file init.lua if it exists, and hence to automatically start the application. One thing to watch out for is that if an error in init.lua causes the device to reset, then it will just continue on in a reset loop until you reflash the device.

To avoid this situation, it is handy to use a timer to give a few seconds delay before calling the main program. If there is a problem, then during this delay it is possible to quickly paste file.remove('init.lua') into the terminal, which will give you back control after the next restart. For example, in init.lua:

print ("Starting in ".. 7 .." seconds ...")
tmr.alarm(1,7000, 0, dofile("broken.lua"))

6.1.5. Compiling .lua Files to .lc Lua Bytecode

Once a .lua file is stored in the flash, the NodeMCU lua compiler can be called to write a corresponding .lc lua-bytecode file. A .lc file will load faster and use less heap memory than an .lua file. For example:

node.compile("hello.lua")
dofile("hello.lc")

6.1.6. Using the C Preprocessor

Lua, being intended for small, embedded systems doesn’t include niceties like being able to define constants or conditional compilation, for example. I have found it useful to name my source files with a .lpp extension and then include C preprocessor directives such as #define along with the Lua code. The Makefile, then runs the .lpp files though the preprocessor to generate the .lua files. Like this:

LPP_SOURCES=cmd.lpp startup.lpp init.lua control.lpp
LUAS=$(LPP_SOURCES:.lpp=.lua)



%.lua: %.lpp
 (cpp | grep -v ‘^#’)  > $@  < $<

all: $(LUAS)

7. Conclusion

I hope that by documenting my getting up to speed with the ESP8266 will help others do similiarly, but without the time involved with having to source all the required information from various sources. Please leave a comment via the link below to let me know how you go, or if you have questions, or corrections etc.