microgear-particle is a client library for Particle Photon/Electron dev board. The library is used to connect application code or hardware with the NETPIE Platform's service for developing IoT applications. For more details on the NETPIE Platform, please visit https://netpie.io .
We have tested this library and found it compatible with (but not limited to) the following hardware
- Spark Core
- Particle Photon
- Particle Electron
Make sure that ports 8080 and 1883 are allowed to connect from your network.
Usage Example
/* NETPIE Particle basic sample */
/* More information visit : https://netpie.io */
#include "MicroGear.h"
#define APPID <APPID>
#define KEY <APPKEY>
#define SECRET <APPSECRET>
#define ALIAS "esp8266"
TCPClient 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++)
Serial.print((char)msg[i]);
Serial.println();
}
void onLostgear(char *attribute, uint8_t* msg, unsigned int msglen) {
Serial.print("Lost member --> ");
for (int i=0; i<msglen; i++)
Serial.print((char)msg[i]);
Serial.println();
}
/* 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 */
microgear.setAlias(ALIAS);
}
void setup() {
/* Add Event listeners */
/* Call onMsghandler() when new message arraives */
microgear.on(MESSAGE,onMsghandler);
/* Call onFoundgear() when new gear appear */
microgear.on(PRESENT,onFoundgear);
/* Call onLostgear() when some gear goes offline */
microgear.on(ABSENT,onLostgear);
/* Call onConnected() when NETPIE connection is established */
microgear.on(CONNECTED,onConnected);
Serial.begin(115200);
Serial.println("Starting...");
/* Initial with KEY, SECRET and also set the ALIAS here */
microgear.init(KEY,SECRET,ALIAS);
/* connect to NETPIE to a specific APPID */
microgear.connect(APPID);
}
void loop() {
/* To check if the microgear is still connected */
if (microgear.connected()) {
Serial.println("connected");
/* Call this method regularly otherwise the connection may be lost */
microgear.loop();
if (timer >= 1000) {
Serial.println("Publish...");
/* Chat with the microgear named ALIAS which is myself */
microgear.chat(ALIAS,"Hello");
timer = 0;
}
else timer += 100;
}
else {
Serial.println("connection lost, reconnect...");
if (timer >= 5000) {
microgear.connect(APPID);
timer = 0;
}
else timer += 100;
}
delay(100);
}
To initial a microgear use one of these methods :
int MicroGear::init(char key, char secret [,char* alias])**
arguments
- 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::on(unsigned char event, void ( callback)(char, uint8_t*,unsigned int))**
Add a callback listener to the event.
arguments
- 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.
arguments
- appid - an App ID.
bool MicroGear::connected()
Check the connection status, return true if it is connected.
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 netpie.io .
arguments
- 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)
arguments
- 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.
arguments
- 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.
arguments
- topic - name of topic to be send a message to.
void MicroGear::unsubscribe(char topic)*
cancel subscription
arguments
- 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
arguments
- 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.
microgear.writeFeed("homesensor","{temp:25.7,humid:62.8,light:8.5}");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 particle loop() function to keep connection alive and to handle incoming messages.