Pinoccio provides an http API, a command line tool, a nodejs API client, and a client side library to build web interfaces to interact with your troops.
The api endpoint is https://api.pinocc.io
Make api calls from your terminal for much win!
curl https://api.pinocc.io/ok
The command line tool is the node module pinoccio
npm install the module globally to get the pinoccio command. you may need to sudo.
sudo npm install -g pinoccioThe pinoccio command should now be avaiable in your terminal. Running pinoccio in the terminal will print a list of avaiable commands.
pinoccio login
pinoccio rest get v1/troops
See the repo on github https://github.com/pinoccio/client-node-pinoccio for more info!
You may load the client side API js directly from https://api.pinocc.io/pinoccio.js
Or you may include it in your projects via browserify by depending on pinoccio node module
Same repo https://github.com/pinoccio/client-node-pinoccio.
Install the module and save the version in your package.json!
npm install --save pinoccio
Include the script tag in your page.
<script src="https://api.pinocc.io/pinoccio.js"></script>This exposes a global pinoccioAPI which you may use like
<script>
var api = pinoccioAPI()
api.rest({url:"/v1/account"},function(err,data){
console.log('much win? ',error,data)
})
</script>
Or require in your browserified client side code (https://www.npmjs.org/package/browserify)
var pinoccio = require('pinoccio');
var api = pinoccio();
console.log('much win!')Creates a new token for making calls against the API.
curl -X POST -v --data '{"email":"youremail","password":"boats"}' https://api.pinocc.io/v1/login
# or you may use query string format
curl -X POST -v --data 'email=youremail&password=boats' https://api.pinocc.io/v1/login
- password
Returns a JSON object with a token and account key in the data property if successful. You will need this session token for all calls that require authentication with the API.
{"data":{"token":"7fc11b7554f0cd303bad94eb0eb36e2d","account":19}}or an error
{"error":{"code":403,"message":"Error: incorrect password"}}Register for pinocc.io
curl -X POST -v --data 'email=youremail&password=boats' https://api.pinocc.io/v1/registerRequired.
- password
- hasAgreedToTerms
Optional.
- firstname
- lastname
Returns a JSON object with a token and account key in the data property if successful. You will need this session token for all calls that require authentication with the API.
{"data":{"token":"7fc11b7554f0cd303bad94eb0eb36e2d","account":19}}Or an error
{"error":{"code":500,"message":"this email is already registered"}}Get your account data
curl 'https://api.pinocc.io/v1/account?token=7fc11b7554f0cd303bad94eb0eb36e2d'
None.
A JSON object of the accout properties.
{
"data":{
"email":"youremail",
"firstname":"",
"lastname":"",
"id":19,
"gravatar":"https://www.gravatar.com/avatar/132e4d83bbcc3b9e53b76d241025481-?d=https%3A%2F%2Fpinocc.io%2Fmodules%2Fcontent%2Ftpl%2Fimages%2Fdefault-avatar.png",
"hasAgreedToTerms":true
}
}Or an error
{"error":{"code":403,"message":"Error: not logged in"}}Logout an auth token
curl -X POST https://api.pinocc.io/v1/logout?token=7fc11b7554f0cd303bad94eb0eb36e2d
-
token
- the token you wish to logout
A json oblect with confirmation.
{"data":true}
Create a "read only" account token. This means you can pass it out and people can only read your troop data but cannot control them.
curl -X POST https://api.pinocc.io/v1/account/token?token=7fc11b7554f0cd303bad94eb0eb36e2d
More granular permission control comming soon.
None. for now.
A json object with the read only view of the account's info.
{"data":{"perms":{"read":true},"firstname":"","lastname":"","account":19,"token":"b27a3af628e595eb6035e6a6c84e3cda","gravatar":"https://www..."}}create a new troop.
curl -X POST 'https://api.pinocc.io/v1/troop?token=7fc11b7554f0cd303bad94eb0eb36e2d'
Optional
- name
an object with the troops data.
{"data":{"id":1,"token":"af49e76320781a7b9722a137039b7f99","account":19,"name":"optional name"}}Or an error
{"error":{"code":403,"message":"Error: not logged in"}}The token here is a unique troop identifier used in provisioning. hq.settoken({troop token})
This troop will NOT appear in GET /v1/troops result until a lead scout with the matching {troop token} connects to base. when this happens it will also create the first scout object for your troop.
Gat all of your accounts troops.
curl 'https://api.pinocc.io/v1/troops?token=7fc11b7554f0cd303bad94eb0eb36e2d'
None.
Data is an array of troop objects.
{"data":[{"id":1,"account":19,"name":"name","online":false}]}Or an error
{"error":{"code":403,"message":"Error: not logged in"}}Get the data for your a troop by troop id
curl 'https://api.pinocc.io/v1/{troop id}?token=7fc11b7554f0cd303bad94eb0eb36e2d'
Required
- v1/{troop id}
Returns a troop object by id. also contains "online" which represents is a lead scout in the troop has an open socket to base
{"data":{"account":19,"id":1,"online":false,"name":"name"}}or an error
{"error":"could not find token for troop 1000"}Note that the name property of the troop object will be undefined if a name was never assigned to the troop.
Update data associated with your troop
curl -X PATCH --data '{"name":"old sport"}' 'https://api.pinocc.io/v1/1?token=7fc11b7554f0cd303bad94eb0eb36e2d'
For right now, name is the only supported key.
Returns the updated troop object
{"data":{"account":"19","token":"af49e76320781a7b9722a137039b7f99","name":"old sport","updated":"1395214271078"}}Delete a troop by troop id. If you have a lead scout provisioned with this troop it will need to be added to a new troop before you can send it commands again.
curl -X DELETE 'https://api.pinocc.io/v1/{troop id}?token=7fc11b7554f0cd303bad94eb0eb36e2d'
- v1/{troop id}
Returns true
{"data":true}Or an error
{"error":"could not find token for troop 1000"}After the troop has been created you will need to access the troop token if you want to provision more scouts.
curl 'https://api.pinocc.io/v1/{troop id}/token?token=7fc11b7554f0cd303bad94eb0eb36e2d'required
- {troop id}
Returns a json string, the troop token.
"af49e76320781a7b9722a137039b7f99"
Add a new scout to your troop
curl -X POST 'https://api.pinocc.io/v1/{troop id}/scout?token=7fc11b7554f0cd303bad94eb0eb36e2d'
- v1/{troop id}
The id in this result is the scout id.
{"data":{"id":1,"time":1388185122294}}In provisioning it must be passed to mesh.config({scout id},{troop id})
Get all of the scouts in your troop.
curl 'https://api.pinocc.io/v1/1/scouts?token=7fc11b7554f0cd303bad94eb0eb36e2d'
- {troop id}
Returns an array of all of the scouts in the troop
{"data":[{"id":1,"time":1388185122294,"updated":1388186085191,"name":"old yeller"}]}Get the data for a scout by id.
curl 'https://api.pinocc.io/v1/{troop id}/{scout id}?token=7fc11b7554f0cd303bad94eb0eb36e2d'- {troop id}
- {scout id}
{"data":{"id":1,"time":1388185122294}}Update data for a scout
For right now, name is the only supported key.
curl -X PATCH --data '{"name":"old yeller"}' 'https://api.pinocc.io/v1/{troop id}/{scout id}?token=7fc11b7554f0cd303bad94eb0eb36e2d'
- {troop id}
- {scout id}
- {name}
{"data":{"id":1,"time":1388185122294,"updated":1388186085191,"name":"old yeller"}}Delete a scout by scout id.
curl -X DELETE 'https://api.pinocc.io/v1/{troop id}/{scout id}?token=7fc11b7554f0cd303bad94eb0eb36e2d'
None.
When you delete a scout, if connected. API will issue a scout.daisy;scout.daisy to reset the scout to factory.
GET /v1/{troop id}/{scout id}/command?command={command}
POST /v1/{troop id}/{scout id}/command data: command={command}
POST /v1/{troop id}/{scout id}/command data: '{"command":"command"}'
Execute bitlash commands on scouts. this includes passing new functions for event handing etc. Commands can be found in the Scout Commands Doc
curl 'https://api.pinocc.io/v1/1/1/command/led.report?token=7fc11b7554f0cd303bad94eb0eb36e2d'
- {troup id}
- {scout id}
- command
- the command may be specifid as a url chunk {command} if it contains vlad uri characters.
- as a query string parameter
- or in post data
Returns the response to the command.
{
data:{
"type":"reply",
"from":1,
"id":"sv90",
"end":true,
"reply":"{\"type\":\"led\",\"led\":[0,0,0],\"torch\":[0,255,0]}",
"account":"19",
"tid":"2",
"_t":1395217755680
}
}or on error
{"error":"scout error: no response true"}Get the state of all of your troops and scouts and realtime events as the state changes. This stream will continue as long as the connection is active.
curl 'https://api.pinocc.io/v1/sync?token=7fc11b7554f0cd303bad94eb0eb36e2d'
optional
-
stale
- default false
- if stale is set to a truthy value (1,true,1337 etc) the last known state of every report will be returned.
- Events the have occured before the last
onlineevent will have a stale:1 flag set. This will help you distinguish reports that may not reflect the current state of your troop.
-
tail
- default true
- if you pass a falsy value (0,false etc) the sync stream will end when it has sent the current state. It will not continue streaming forever
data is newline delimited json.
{"data":{"account":"19","troop":"2","type":"connection","value":{"status":"online","ip":"192.168.43.157"},"time":1395217621149}}
{"data":{"account":"19","troop":"2","scout":"1","type":"analog","value":{"type":"analog","mode":[-1,-1,-1,-1,-1,-1,-1,-1],"state":[-1,-1,-1,-1,-1,-1,-1,-1],"_t":1395217621339.001},"time":1395217621339.001}}
{"data":{"account":"19","troop":"2","scout":"1","type":"available","value":{"scout":1,"available":1,"_t":1395219255686.001,"type":"available"},"time":1395219255686.001}}
{"data":{"account":"19","troop":"2","scout":"1","type":"backpacks","value":{"type":"backpacks","list":[],"_t":1395217621338.001},"time":1395217621338.001}}
{"data":{"account":"19","troop":"2","scout":"1","type":"digital","value":{"type":"digital","mode":[-1,-1,-1,-1,-1,-1,-1],"state":[-1,-1,-1,-1,-1,-1,-1],"_t":1395217621339},"time":1395217621339}}
{"data":{"account":"19","troop":"2","scout":"1","type":"led","value":{"type":"led","led":[0,0,0],"torch":[0,255,0],"_t":1395217754435},"time":1395217754435}}
{"data":{"account":"19","troop":"2","scout":"1","type":"mesh","value":{"type":"mesh","scoutid":1,"troopid":2,"routes":3,"channel":20,"rate":"250 kb/s","power":"3.5 dBm","_t":1395217621340},"time":1395217621340}}
{"data":{"account":"19","troop":"2","scout":"1","type":"power","value":{"type":"power","battery":99,"voltage":415,"charging":false,"vcc":true,"_t":1395217621338},"time":1395217621338}}
{"data":{"account":"19","troop":"2","scout":"1","type":"scout","value":{"type":"scout","lead":true,"version":1,"hardware":1,"family":1000,"serial":2000193,"build":2014031102,"_t":1395217621255},"time":1395217621255}}
{"data":{"account":"19","troop":"2","scout":"1","type":"temp","value":{"type":"temp","current":41,"high":41,"low":34,"_t":1395219407355},"time":1395219407355}}
{"data":{"account":"19","troop":"2","scout":"1","type":"uptime","value":{"type":"uptime","millis":33083780,"free":18521,"random":15089,"reset":"External","_t":1395217621337},"time":1395217621337}}
Get a stream of time series data from start time to end time for any report.
- if no end time is provided or the end time is in the future events will continue as they happen in real time.
- if no start time is provided you will ony get events starting from now as they happen in real time.
curl 'https://api.pinocc.io/v1/stats?token=7fc11b7554f0cd303bad94eb0eb36e2d&report={report}&scout={scout id}&troop={troop id}'
here is a live example. getting all led reports for a time range
required
- troop
- report
- the name of the report you would like to pull.
- led, power, temp, uptime, mesh, digital, backpacks, analog, announce
optional
- scout
- the scout id to get reports for instead of all the scouts in a troop. This is now optional!
- start
- the unix timestamp to in ms start streaming data from.
- end
- the unix timestamp in ms to stop streaming data from.
- tail
- if i have no more old data should i wait for new data to arrive?
Data is newline delimited json. sorted by time. Below are is example of power reports.
{"data":{"account":"19","troop":"1","scout":"1","type":"power","value":{"type":"power","battery":96,"voltage":415,"charging":false,"vcc":true,"_t":1395176893461.001},"time":1395176893461.001}}
{"data":{"account":"19","troop":"1","scout":"1","type":"power","value":{"type":"power","battery":96,"voltage":413,"charging":false,"vcc":true,"_t":1395176943720},"time":1395176943720}}
{"data":{"account":"19","troop":"1","scout":"1","type":"power","value":{"type":"power","battery":96,"voltage":410,"charging":false,"vcc":true,"_t":1395177123715},"time":1395177123715}}
{"data":{"account":"19","troop":"1","scout":"1","type":"power","value":{"type":"power","battery":96,"voltage":418,"charging":false,"vcc":true,"_t":1395177183714},"time":1395177183714}}
{"data":{"account":"19","troop":"1","scout":"1","type":"power","value":{"type":"power","battery":96,"voltage":418,"charging":true,"vcc":true,"_t":1395177183863},"time":1395177183863}}
{"data":{"account":"19","troop":"1","scout":"1","type":"power","value":{"type":"power","battery":97,"voltage":418,"charging":true,"vcc":true,"_t":1395177363708},"time":1395177363708}}
{"data":{"account":"19","troop":"1","scout":"1","type":"power","value":{"type":"power","battery":98,"voltage":415,"charging":false,"vcc":true,"_t":1395178209292},"time":1395178209292}}
{"data":{"account":"19","troop":"1","scout":"1","type":"power","value":{"type":"power","battery":98,"voltage":415,"charging":false,"vcc":true,"_t":1395178940937.001},"time":1395178940937.001}}
{"data":{"account":"19","troop":"1","scout":"1","type":"power","value":{"type":"power","battery":98,"voltage":412,"charging":false,"vcc":true,"_t":1395185082971},"time":1395185082971}}
{"data":{"account":"19","troop":"1","scout":"1","type":"power","value":{"type":"power","battery":98,"voltage":413,"charging":false,"vcc":true,"_t":1395185083581},"time":1395185083581}}
{"data":{"account":"19","troop":"1","scout":"1","type":"power","value":{"type":"power","battery":98,"voltage":413,"charging":true,"vcc":true,"_t":1395185083683},"time":1395185083683}}
{"data":{"account":"19","troop":"2","scout":"1","type":"power","value":{"type":"power","battery":99,"voltage":418,"charging":true,"vcc":true,"_t":1395185383644},"time":1395185383644}}
{"data":{"account":"19","troop":"2","scout":"1","type":"power","value":{"type":"power","battery":99,"voltage":416,"charging":true,"vcc":true,"_t":1395185503642},"time":1395185503642}}
{"data":{"account":"19","troop":"2","scout":"1","type":"power","value":{"type":"power","battery":99,"voltage":416,"charging":false,"vcc":true,"_t":1395185503726},"time":1395185503726}}
{"data":{"account":"19","troop":"2","scout":"1","type":"power","value":{"type":"power","battery":99,"voltage":415,"charging":false,"vcc":true,"_t":1395185563641},"time":1395185563641}}
{"data":{"account":"19","troop":"2","scout":"1","type":"power","value":{"type":"power","battery":99,"voltage":415,"charging":false,"vcc":true,"_t":1395217621338},"time":1395217621338}}
With curl or the cli tool it streams to stdout, in the nodejs API client it returns a stream.