NETPIE client library for ESP8266
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Add Basic Asynchronous Publish example. (#8) Aug 26, 2016
AuthClient.cpp add setConfig function Apr 24, 2017
AuthClient.h change place to define gearauth endpoint Apr 24, 2017
MicroGear.cpp add setConfig function Apr 24, 2017
PubSubClient.cpp add connection state checking function, auto reset token if token is … Dec 7, 2015
PubSubClient.h Add #ifdefine to override default PubSubClient value. Jun 18, 2016 Use setAlias instead of setname (#15) Oct 27, 2017 Use setAlias instead of setname (#15) Oct 27, 2017
SHA1.h initial commit Jul 27, 2015
debug.h initial commit Jul 27, 2015 increase version Apr 24, 2017


microgear-esp8266-arduino is a client library that is used to connect an ESP8266 chip to the NETPIE Platform's service for developing IoT applications. For more details on the NETPIE Platform, please visit .


We have tested this library and found it compatible with (but not limited to) the following hardware

  • ESP8266-01, 07, 12E, 12F
  • NodeMCU v1, v2, V3
  • Espresso Lite v2.0

Outgoing Network Port

Make sure ther following ports are allowed to connect from your network.

  • Non-TLS mode : 8080 and 1883 (the library uses this mode by default)
  • TLS mode : 8081 and 8883 (still under testing)


Known Issues

  • TLS works fine on ESP8266 SDK 2.1.0 but has an issue with 2.2.0. However it works again with 2.3.0-rc1

Usage Example

/*  NETPIE ESP8266 basic sample                            */
/*  More information visit :             */

#include <ESP8266WiFi.h>
#include <MicroGear.h>

const char* ssid     = <WIFI_SSID>;
const char* password = <WIFI_KEY>;

#define APPID   <APPID>
#define KEY     <APPKEY>
#define ALIAS   "esp8266"

WiFiClient client;

int timer = 0;
MicroGear microgear(client);

/* If a new message arrives, do this */
void onMsghandler(char *topic, uint8_t* msg, unsigned int msglen) {
    Serial.print("Incoming message --> ");
    msg[msglen] = '\0';
    Serial.println((char *)msg);

void onFoundgear(char *attribute, uint8_t* msg, unsigned int msglen) {
    Serial.print("Found new member --> ");
    for (int i=0; i<msglen; i++)

void onLostgear(char *attribute, uint8_t* msg, unsigned int msglen) {
    Serial.print("Lost member --> ");
    for (int i=0; i<msglen; i++)

/* When a microgear is connected, do this */
void onConnected(char *attribute, uint8_t* msg, unsigned int msglen) {
    Serial.println("Connected to NETPIE...");
    /* Set the alias of this microgear ALIAS */

void setup() {
    /* Add Event listeners */
    /* Call onMsghandler() when new message arraives */

    /* Call onFoundgear() when new gear appear */

    /* Call onLostgear() when some gear goes offline */

    /* Call onConnected() when NETPIE connection is established */


    /* Initial WIFI, this is just a basic method to configure WIFI on ESP8266.                       */
    /* You may want to use other method that is more complicated, but provide better user experience */
    if (WiFi.begin(ssid, password)) {
        while (WiFi.status() != WL_CONNECTED) {

    Serial.println("WiFi connected");  
    Serial.println("IP address: ");

    /* Initial with KEY, SECRET and also set the ALIAS here */

    /* connect to NETPIE to a specific APPID */

void loop() {
    /* To check if the microgear is still connected */
    if (microgear.connected()) {

        /* Call this method regularly otherwise the connection may be lost */

        if (timer >= 1000) {

            /* Chat with the microgear named ALIAS which is myself */
            timer = 0;
        else timer += 100;
    else {
        Serial.println("connection lost, reconnect...");
        if (timer >= 5000) {
            timer = 0;
        else timer += 100;

Library Usage

To initial a microgear use one of these methods :

int MicroGear::init(char key, char secret [,char* alias])**


  • key - is used as a microgear identity.
  • secret - comes in a pair with gearkey. The secret is used for authentication and integrity.
  • alias - specifies the device alias (optional).
microgear.init("sXfqDcXHzbFXiLk", "DNonzg2ivwS8ceksykGntrfQjxbL98", "myplant");

void MicroGear:: setEEPROMOffset(int offset)

Shift the offset of an EEPROM address where a microgear token is stored. This command will be useful if your application wants to store some other data in an EEPROM as well. The default offset value is 0.



  • offset - The EEPROM address offset vale. The default is 0.

void MicroGear::on(unsigned char event, void ( callback)(char, uint8_t*,unsigned int))**

Add a callback listener to the event.


  • event - a name of the event (MESSAGE|CONNECTED|PRESENT|ABSENT).
  • callback - a callback function .

int MicroGear::connect(char appid)*

Connect to NETPIE. If succeed, a CONNECTED event will be fired. The function returns the following code

  • NETPIECLIENT_CONNECTED - The connection is successful.
  • NETPIECLIENT_NOTCONNECTED - The connection to the broker cannot be initiated.
  • NETPIECLIENT_TOKENERROR - An access token is not issued, may be because an appid, a key or a secret is invalid.


  • appid - an App ID.

bool MicroGear::connected()

Check the connection status, return true if it is connected.

void MicroGear::useTLS(bool enabled)*

Switch between uncrypted and TLS mode (by default the library does not use TLS). This function must be called before the connection is made.


  • enabled - set to TRUE to use TLS.

void MicroGear::setAlias(char alias)*

microgear can set its own alias, which to be used for others make a function call chat(). The alias will appear on the key management portal of .


  • alias - an alias.

bool MicroGear::chat(char target, char message)
bool MicroGear::chat(char target, int message)

bool MicroGear::chat(char target, double message)

bool MicroGear::chat(char target, double, int decimal)
bool MicroGear::chat(char target, String message)


  • target - the alias of the microgear(s) that a message will be sent to.
  • message - message to be sent.
  • decimal - number of digits after the deimal point.

bool MicroGear::publish(char topic, char message [, bool retained])
bool MicroGear::publish(char topic, double message [, bool retained])

bool MicroGear::publish(char topic, double message, int decimal [, bool retained])

bool MicroGear::publish(char topic, int message [, bool retained])
bool MicroGear::publish(char topic, String message [, bool retained])

In the case that the microgear want to send a message to an unspecified receiver, the developer can use the function publish to the desired topic, which all the microgears that subscribe such topic will receive a message.


  • topic - name of topic to be send a message to.
  • message - message to be sent.
  • decimal - number of digits after the deimal point.
  • retained - retain a message or not, the default is false (optional))

void MicroGear::subscribe(char topic)*

microgear may be interested in some topic. The developer can use the function subscribe() to subscribe a message belong to such topic. If the topic used to retain a message, the microgear will receive a message everytime it subscribes that topic.


  • topic - name of topic to be send a message to.

void MicroGear::unsubscribe(char topic)*

cancel subscription


  • topic - name of topic to be send a message to.

void microgear.writeFeed (char feedid, char *datajson)
void microgear.writeFeed (char feedid, char *datajson, char *apikey)

void microgear.writeFeed (char feedid, String datajson)
void microgear.writeFeed (char feedid, String datajson, char *apikey)

write time series data to a feed storage


  • feedid - name of the feed
  • datajson - data string in json format
  • apikey - apikey for authorization. If apikey is not specified, you will need to allow the AppID to access feed and then the default apikey will be assigned automatically.

void MicroGear::resetToken()

To send a revoke token control message to NETPIE and delete the token from cache. As a result, the microgear will need to request a new token for the next connection.

void MicroGear::loop()

This method has to be called regularly in the arduino loop() function to keep connection alive and to handle incoming messages.