Cloud API documentation?

Koos du Preez

Does anyone know if there is any docs or info avaialble on the cloud API ?

i.e. if i want to call gpio control functions via the endpoint api.onion.io/v1/devices/[deviceid]/onion/gpio

what are syntax and values for the parameters and command options ?

Koos du Preez

nothing, eh ??

Balda

Hi

In https://cloud.onion.io/, when you are in Device Explorer App, the browser make a request to https://api.onion.io/v1/devices/[devide-id]/file/exec with JSON POST params { "command": "ubus", "params": [ "-v", "list" ] } to query API objects and methods (and with good auth token).

So to get complete list of available API services, commands and params (with expected type), execute ubus -v list in the omega shell.

In my Omega2+ (0.1.9 b149) i have:

root@Omega-XXXX:~# ubus -v list
'dhcp' @9de6b875
	"ipv4leases":{}
	"ipv6leases":{}
'file' @88fe19bc
	"read":{"path":"String","base64":"Boolean"}
	"write":{"path":"String","data":"String","append":"Boolean","mode":"Integer","base64":"Boolean"}
	"list":{"path":"String"}
	"stat":{"path":"String"}
	"md5":{"path":"String"}
	"exec":{"command":"String","params":"Array","env":"Table"}
'i2c_exp' @9715ff56
	"pwm-exp":{"command":"String","params":"Table"}
	"relay-exp":{"command":"String","params":"Table"}
	"oled-exp":{"command":"String","option":"String","params":"Table"}
	"status":{}
'iwinfo' @2518fe83
	"devices":{}
	"info":{"device":"String"}
	"scan":{"device":"String"}
	"assoclist":{"device":"String","mac":"String"}
	"freqlist":{"device":"String"}
	"txpowerlist":{"device":"String"}
	"countrylist":{"device":"String"}
	"phyname":{"section":"String"}
'log' @8e44d751
	"read":{"lines":"Integer","stream":"Boolean"}
	"write":{"event":"String"}
'network' @a0d31090
	"restart":{}
	"reload":{}
	"add_host_route":{"target":"String","v6":"Boolean","interface":"String"}
	"get_proto_handlers":{}
	"add_dynamic":{"name":"String"}
'network.device' @967b37d6
	"status":{"name":"String"}
	"set_alias":{"alias":"Array","device":"String"}
	"set_state":{"name":"String","defer":"Boolean"}
'network.interface' @22b5dacb
	"up":{}
	"down":{}
	"status":{}
	"prepare":{}
	"dump":{}
	"add_device":{"name":"String","link-ext":"Boolean"}
	"remove_device":{"name":"String","link-ext":"Boolean"}
	"notify_proto":{}
	"remove":{}
	"set_data":{}
'network.interface.loopback' @a6f7dd81
	"up":{}
	"down":{}
	"status":{}
	"prepare":{}
	"dump":{}
	"add_device":{"name":"String","link-ext":"Boolean"}
	"remove_device":{"name":"String","link-ext":"Boolean"}
	"notify_proto":{}
	"remove":{}
	"set_data":{}
'network.interface.wan' @22ae2bbe
	"up":{}
	"down":{}
	"status":{}
	"prepare":{}
	"dump":{}
	"add_device":{"name":"String","link-ext":"Boolean"}
	"remove_device":{"name":"String","link-ext":"Boolean"}
	"notify_proto":{}
	"remove":{}
	"set_data":{}
'network.interface.wlan' @6c4c466f
	"up":{}
	"down":{}
	"status":{}
	"prepare":{}
	"dump":{}
	"add_device":{"name":"String","link-ext":"Boolean"}
	"remove_device":{"name":"String","link-ext":"Boolean"}
	"notify_proto":{}
	"remove":{}
	"set_data":{}
'network.interface.wwan' @22b2f540
	"up":{}
	"down":{}
	"status":{}
	"prepare":{}
	"dump":{}
	"add_device":{"name":"String","link-ext":"Boolean"}
	"remove_device":{"name":"String","link-ext":"Boolean"}
	"notify_proto":{}
	"remove":{}
	"set_data":{}
'network.wireless' @9d8e2591
	"up":{}
	"down":{}
	"status":{}
	"notify":{}
	"get_validate":{}
'onion' @1a5fd088
	"wifi-scan":{"device":"String"}
	"wifi-setup":{"params":"Table"}
	"oupgrade":{"params":"Table"}
	"dir-list":{"directory":"String"}
	"omega-led":{"set_trigger":"String","read_triggers":"Boolean"}
	"fast-gpio":{"params":"Table"}
	"i2c-scan":{}
	"rgb-led":{"command":"String","params":"Table"}
	"gpio":{"command":"String","params":"Table"}
	"launch-process":{"command":"String"}
	"status":{}
'onion-console' @762ce66b
	"app-list":{}
	"shellinabox":{"params":"Table"}
	"status":{}
'onion-helper' @729df88d
	"background":{"command":"String","params":"Array"}
	"echo":{"message":"String"}
	"write":{"path":"String","data":"String","append":"Boolean","mode":"Integer","base64":"Boolean"}
	"download":{"url":"String","path":"String","background":"Boolean"}
'rpc-sys' @309860e6
	"password_set":{"user":"String","password":"String"}
	"upgrade_test":{}
	"upgrade_start":{"keep":"Boolean"}
	"upgrade_clean":{}
	"factory":{}
	"reboot":{}
'service' @485cfe4d
	"set":{"name":"String","script":"String","instances":"Table","triggers":"Array","validate":"Array"}
	"add":{"name":"String","script":"String","instances":"Table","triggers":"Array","validate":"Array"}
	"list":{"name":"String","verbose":"Boolean"}
	"delete":{"name":"String","instance":"String"}
	"signal":{"name":"String","instance":"String","signal":"Integer"}
	"update_start":{"name":"String"}
	"update_complete":{"name":"String"}
	"event":{"type":"String","data":"Table"}
	"validate":{"package":"String","type":"String","service":"String"}
	"get_data":{"name":"String","instance":"String","type":"String"}
'session' @0bc85bc7
	"create":{"timeout":"Integer"}
	"list":{"ubus_rpc_session":"String"}
	"grant":{"ubus_rpc_session":"String","scope":"String","objects":"Array"}
	"revoke":{"ubus_rpc_session":"String","scope":"String","objects":"Array"}
	"access":{"ubus_rpc_session":"String","scope":"String","object":"String","function":"String"}
	"set":{"ubus_rpc_session":"String","values":"Table"}
	"get":{"ubus_rpc_session":"String","keys":"Array"}
	"unset":{"ubus_rpc_session":"String","keys":"Array"}
	"destroy":{"ubus_rpc_session":"String"}
	"login":{"username":"String","password":"String","timeout":"Integer"}
'system' @39d2d5f9
	"board":{}
	"info":{}
	"upgrade":{}
	"reboot":{}
	"watchdog":{"frequency":"Integer","timeout":"Integer","stop":"Boolean"}
	"signal":{"pid":"Integer","signum":"Integer"}
	"nandupgrade":{"path":"String"}
'uci' @81308949
	"configs":{}
	"get":{"config":"String","section":"String","option":"String","type":"String","match":"Table","ubus_rpc_session":"String"}
	"state":{"config":"String","section":"String","option":"String","type":"String","match":"Table","ubus_rpc_session":"String"}
	"add":{"config":"String","type":"String","name":"String","values":"Table","ubus_rpc_session":"String"}
	"set":{"config":"String","section":"String","type":"String","match":"Table","values":"Table","ubus_rpc_session":"String"}
	"delete":{"config":"String","section":"String","type":"String","match":"Table","option":"String","options":"Array","ubus_rpc_session":"String"}
	"rename":{"config":"String","section":"String","option":"String","name":"String","ubus_rpc_session":"String"}
	"order":{"config":"String","sections":"Array","ubus_rpc_session":"String"}
	"changes":{"config":"String","ubus_rpc_session":"String"}
	"revert":{"config":"String","ubus_rpc_session":"String"}
	"commit":{"config":"String","ubus_rpc_session":"String"}
	"apply":{"rollback":"Boolean","timeout":"Integer","ubus_rpc_session":"String"}
	"confirm":{"ubus_rpc_session":"String"}
	"rollback":{"ubus_rpc_session":"String"}
	"reload_config":{}

As you can see, format is like:

'service' @39d2d5f9
	"command": {
		"param": "Type of the param"
	}

Hope it helps

Patrick Rainsberry

I was trying to use the device explorer to generate the commands but was getting stuck? I can get status of device with 'i2c_exp' end point successfully

When i try to use 'oled-exp' i am using the following for the parameters:

command: write
options: -c
parameters: ["test"]

seems parameters wants a table, this was the only way i could get it to work. I think you maybe have a mistake in there?

Shouldn't it be the other way around?

From docs:
oled-exp [OPTIONS] <COMMAND> <PARAMETER>

I believe maybe you transposed the types on options and parameters? options should be table and parameters a string?

Balda

In the file/exec service, Table is an object (env key: value). I don't understand Table type for oled-exp params (we don't need keys).

You can use file/exec with

{
  "command": "oled-exp",
  "params": [ "-q", "write", "test" ]
}

works for me

I'll try to make Table params working.

Manuel Godinez

Have a question to you guys regarding Device Explorer App in the cloud:

How does one actually make it work? Can someone tell me the steps to do, let's say, set the onborard led to heartbeat mode...

Do I need to copy the commands and paste it somewhere? I have no clue on how it actually works the Device Explorer App and any help would be appreciate it.

Costas Costas

@Koos-du-Preez bit of documentation on the GitHub at https://github.com/OnionIoT/onion-ubus#gpio

@Manuel-Godinez I know many people start with controlling the onboard LED's but I'm guessing that ultimately you will want to control the GPIO pins. Also the LED was a bit flakey for me when I tried but it works up to a point and certainly works with console commands. With the GPIO details below and the syntax from the url you can check out LED's if you want to try.

If you are connected to the Device Explorer via the cloud and enter the correct commands and parameters you can control the pins from the web interface.

So command get and params {"gpio":"0"} will return:

    "success": true,
    "pin": "0",
    "value": "0"
}

Command set and params {"gpio":"1","value":"1"} will return the following and can be checked with a follow up get

{
    "success": true,
    "pin": "1",
    "value": "1"
}

Ultimately some users will want to control the pins via their own web interface or application. So if you obtain an API key and click the Generate Code button it will give you curl, C, Python and NodeJS versions of the required code.

The Device Explorer is considered to be a bit buggy by some people as you have to ensure the data in the fields is not "cached" but if you retype the data in the fields and move to another field it works as expected.

Manuel Godinez

@Costas-Costas said in Cloud API documentation?:

{"gpio":"1","value":"1"}

Great, I am just wondering, what option do you choose first, onion, uci or service?

See the following screenshot and it these are the steps to follow?
https://www.screencast.com/t/rS4t3tNDEr

Thanks

Manuel Godinez

After much testing, I found the answer So now I can use the Device Explorer App from the cloud, but as Costas said, it is always better to control from our own web interface. Thing is, I can't seem to find and PHP examples on using the gpio pins. The code that produces the Device Explorer also, relies on the onion server. Would there be a way to directly connect to the Onion2 instead of going from our own web server to the onion server and then to the Omega2????

Costas Costas

@Manuel-Godinez strange screenshot you have for the Onion ubus. Actually that is the Service ubus but I guess you found Onion ubus.

If, like me, you are not easily able to translate C, Python and NodeJS to PHP then what you can do is use one of the many online converters. If you enter the curl command at https://curl.trillworks.com/#php it will return the PHP code for you.

Regarding the different servers what I do to remove the Onion servers is go via Blynk http://www.blynk.cc/getting-started/

Blynk have an opensource server on the cloud and you can use their's, host yours on the cloud or have a local server with port forwarding etc.

Manuel Godinez

@Costas-Costas Yes, after much trial and error I got the PHP code to work now
Thanks though for the online converter, it might come handy in the future.

I had use Blynk with Arduino but not that much, only a few tests and did something else. Will take a look at it again.
Thanks!

Costas Costas

@Manuel-Godinez I have used Blynk with Arduino's but I have found it works better with MCU's that have inbuilt WiFi.

The setup details provided by Omega for Blynk are at https://wiki.onion.io/Tutorials/blynk-library
It needs an update for the Omega +2 pinout but the developers at Blynk have it in their roadmap. Meanwhile you can just use pins that were common to the original Omega and the new 2's. You need a 2+ or a 2 with USB Stick to run Blynk.

You can see a screenshot of Omega 2+ with Blynk in this thread http://community.onion.io/topic/1115/the-onion-thermostat/7

Manuel Godinez

@Costas-Costas Sorry for my ignrance but what do you mean that I need an Omega2+ or Omega2 with a USB flash drive???

Costas Costas

@Manuel-Godinez it will run on an Omega2+ as it is but not enough space on a regular 2.
It needs around 11MB and a stock Onion is about 1 to 2MB short. Might be you could remove some stuff if you didn't want to run from a USB stick on a regular 2.

Steve Smythe

I am trying to use IFTTT to send a web request to my Omega 2+ to switch on GPIO 0. However, I can't seem to get the right format for IFTTT. The data shown in the attached screenshot generates an error in IFTTT about the use of {{

Any idea what I am doing wrong?

Steve Smythe

Solved it! You need to add a space in between the last two curly brackets.

Steve Smythe

Before using the above method to turn on a GPIO using IFTTT, I should also point out that you need to set the relevant GPIO pin as an output first. You can do this with a separate IFTTT Applet. I haven't been able to concatenate two GPIO command strings in one IFTTT Applet (i.e. send {"command":"set-direction", "params":{"gpio":"0", "value":"output"} } then send {"command":"set","params":{"gpio":"0","value":"1"} } ).

Anybody know if this is possible?

Balda

https://sdk.onion.io/reference/onion-cloud-APIs/device-api.html

Yeah! Documentation!

alpha23

This post is deleted!

alpha23

@Steve-Smythe I was able to use launch-process to run a quick script. You could write a script to set direction of the gpio pin and then to execute high or low. I got it to work in the ifttt channel.