CPT Web API HowTo Document · 12/6/2018 · Introduction This Document will show you how to use...

CPT Web API HowTo DocumentEasyIO

Version 1.0, 2018-12-06

Table of ContentsIntroduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

CPT Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

easyioCpt Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Step 0: Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Step 1: Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Authentication using plain text password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Authentication using password hash (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Step 2: Read Sedona Object Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Step 3.1: Change Sedona Object Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Step 3.2: Invoke Sedona Object Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

invoke action with parameter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

invoke action without parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Step 3.3: Send Multiple Write Commands within One HTTP Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Prerequisite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

How to send Multi-Write command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Multi-Write command for slot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Multi-Write command for action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Backup & Restore API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Fetch Backup List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Make New Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Restore a Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Delete a Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Application Level Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Sedona Object Data Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

How to set up demo script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Change Controller’s DateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

IntroductionThis Document will show you how to use CPT web’s data API to read and write sedona object’s datafrom your code.

The CPT web data service is built in RESTful style, in short, HTTP GET method is used to read data;HTTP POST method is used to write or change data.

All requests must be Ajax request, and all responses are returned in JSON format. Ifyou use normal HTTP request, the returned data will be different compared withAjax request.

Requirements

CPT ToolsThe version must have graphics feature enabled.

easyioCpt KitVersion 1.0.45.33+. After the kit is installed, create an object of easyioCpt::cptService under servicefolder, and make sure the object’s is enabled and its status is Ok.

Step 0: DeploymentFirst, you will need to make sure the CPT web service has been deployed on device. You have notdone it, you can follow the instructions below:

1. launch CPT Tools

2. connect to controller

3. double click Welcome under Graphics navigation tree to open it

4. run full deployment

Step 1: AuthenticationTo communicate with the data service API, you need to signin first.

There are two ways to do authentication, the difference is about how to transfer password betweenbrowser and server. You can transfer password in plain text; or for higher security, you can hashthe password using authToken from server side first, then pass it to server. The later way isrecommended for security reason.

1

http://en.wikipedia.org/wiki/Representational_state_transfer

Authentication using plain text passwordFollowing codes show how to signin using jQuery:

$.ajax({ url: "http://192.168.10.11/sdcard/cpt/app/signin.php", type: 'POST', dataType: 'json', data: { 'user[name]': 'admin', 'user[password]': 'hellocpt' }}).done(function(data) { console.debug("signin done");});

if your service is not running on the same host as CPT Graphic Web Service, thendue to the Same-origin policy, you need to make sure every http ajax request sentfrom browser has CORS(Cross Origin Resource Sharing) headers:

$.ajax({ url: '...', type: '...', dataType: '...', xhrFields: { withCredentials: true }, headers: {'X-Requested-With': 'XMLHttpRequest'}, data: {...} })

or with curl

curl -X POST -c cookies.txt -H "X-Requested-With: XMLHttpRequest" \ -d "user%5Bname%5D=admin&user%5Bpassword%5D=hellocpt" \ http://192.168.10.11/sdcard/cpt/app/signin.php

Authentication using password hash (recommended)This method will not pass password in plain text to server, instead it will hash password first, thenpass the password hash. This will make authentication more secure (or harder to be hacked) onHTTP. If you want absolute security, you should switch to HTTPS.

To hash password before signin, you will need to fetch the authToken first.

Following code example uses jsSHA ("a JavaScript implementation of the completeSecure Hash Standard family") to generate password hash, you will need todownload it and include sha1.js.

2

https://en.wikipedia.org/wiki/Same-origin_policy

http://curl.haxx.se/

https://github.com/Caligatio/jsSHA

$.ajax({ url: 'http://192.168.10.11/sdcard/cpt/app/signin.php', type: "GET", dataType: 'json', data: {'user[name]': 'admin'},}).done(function(data) { if (!data.authToken) { console.error("failed to fetch authToken"); return; } var sections = data.authToken.split('_'); if (sections.length != 2) { console.warn("invalid authToken: " + data.authToken); return; }

var token1 = sections[0]; var token2 = sections[1];

// to calculate password hash, there are 2 steps: // 1. calculate SHA-1 hash for password + token1 // 2. calculate SHA-1 hash for result of step1 + token2 var password = 'hellocpt'; var shaObj1 = new jsSHA(password + token1, 'TEXT'); var shaObj2 = new jsSHA(shaObj1.getHash('SHA-1', 'HEX') + token2, 'TEXT'); var authHash = shaObj2.getHash('SHA-1', 'HEX');

$.ajax({ url: 'http://192.168.10.11/sdcard/cpt/app/signin.php', type: 'POST', dataType: 'json', data: { 'user[name]': 'admin', 'user[authHash]': authHash } }).done(function(data) { console.debug("signin done"); });});

or with curl:

3


curl -H "X-Requested-With: XMLHttpRequest"'http://192.168.10.11/sdcard/cpt/app/signin.php?user%5Bname%5D=admin'

# calculate password hash... ...

curl -X POST -c cookies.txt -H "X-Requested-With: XMLHttpRequest" \ -d "user%5Bname%5D=admin&user%5BauthHash%5D=$AUTHHASH" \ http://192.168.10.11/sdcard/cpt/app/signin.php

Step 2: Read Sedona Object DataAfter signed in successfully, you can read data at 192.168.10.11/sdcard/cpt/app/data_api.php?url=/app/objectsSEDONA_OBJECT_PATH_LIST using HTTP GET method. For example:

varurl='http://192.168.10.11/sdcard/cpt/app/data_api.php?url=/app/objects/EasyIO/Ramp.out';$.ajax( {url: url, type: 'GET', dataType: 'json'} ).done(function(data) {console.debug(data);});

or with curl:

curl -X GET -H "X-Requested-With: XMLHttpRequest" -b cookies.txt \ 'http://192.168.10.11/sdcard/cpt/app/data_api.php?url=/app/objects/EasyIO/Ramp.out'

The response data is returned in json format:

4

http://192.168.10.11/sdcard/cpt/app/data_api.php?url=/app/objectsSEDONA_OBJECT_PATH_LIST
















{ "response" : { "resultCode" : 0, // '0' for success, other numbers for failure "data" : [ // sedona object data is orgnized in list { // every object's data is a dictionary "path" : "/EasyIO/Ramp", //sedona object's path "slots" : [ //slots data is organized as a list { "value" : "49.000000", // 'out' slot's value "slotType" : "property", // this slot is a property "name" : "out", // slot's name "type" : "float" // slot value's data type } ] } ] }}

SEDONA_OBJECT_PATH_LIST is the required sedona objects' paths, if there are multiple sedona objectsrequired, joining them using ~. For examples:

To read all slots of sedona object '/EasyIO/Ramp':

The URL is: 192.168.10.11/sdcard/cpt/app/data_api.php?url=/app/objects/EasyIO/Ramp

To read only out slot data of sedona object '/EasyIO/Ramp':

The URL is: 192.168.10.11/sdcard/cpt/app/data_api.php?url=/app/objects/EasyIO/Ramp.out

To read all slots of sedona objects '/EasyIO/Ramp' and '/EasyIO/Ramp2':

The URL is: 192.168.10.11/sdcard/cpt/app/data_api.php?url=/app/objects/EasyIO/Ramp~/EasyIO/Ramp2

To read some slots of a sedona objects '/EasyIO/Add2' and all slots of '/EasyIO/Ramp':

The URL is: http://192.168.10.11/sdcard/cpt/app/data_api.php?url=/app/objects/EasyIO/Add2.out~/EasyIO/Add2.in1~/EasyIO/Ramp

If easyioCpt kit >= v1.0.45.35.9, then the URL can also be shortened like this: http://192.168.10.11/sdcard/cpt/app/data_api.php?url=/app/objects/EasyIO/Add2.out%2Bin1%2Bin2~/EasyIO/Ramp (%2B isthe URL safe version of character '+')

Step 3.1: Change Sedona Object DataTo change sedona object’s data, you will need to send a HTTP POST request to URL 192.168.10.11/sdcard/cpt/app/data_api.php.

For example, following codes will change value of slot /EasyIO/WriteIn.in to 100:

5

http://192.168.10.11/sdcard/cpt/app/data_api.php?url=/app/objects/EasyIO/Ramp



















http://192.168.10.11/sdcard/cpt/app/data_api.php?url=/app/objects/EasyIO/Ramp.out



















http://192.168.10.11/sdcard/cpt/app/data_api.php?url=/app/objects/EasyIO/Ramp~/EasyIO/Ramp2























http://http://192.168.10.11/sdcard/cpt/app/data_api.php?url=/app/objects/EasyIO/Add2.out~/EasyIO/Add2.in1~/EasyIO/Ramp



























http://http://192.168.10.11/sdcard/cpt/app/data_api.php?url=/app/objects/EasyIO/Add2.out%2Bin1%2Bin2~/EasyIO/Ramp























http://192.168.10.11/sdcard/cpt/app/data_api.php









invoke action with parameterThe request to invoke a sedona object’s action is almost the same as changing object’s data:

var url = 'http://192.168.10.11/sdcard/cpt/app/data_api.php';$.ajax({ url: url, type: 'POST', dataType: 'json', data: { path: '/app/objects/EasyIO/ConstFl.set', type: 'float', value: '37', slotType: 'action' } }).done(function(data) { console.debug(data); });

or with curl:

curl -X POST -H "X-Requested-With: XMLHttpRequest" -b cookies.txt \ -d 'path=/app/objects/EasyIO/ConstFl.set&type=float&value=37&slotType=action' \ http://192.168.10.11/sdcard/cpt/app/data_api.php


{ "response" : { "resultCode" : 0, // '0' means success, other numbers mean failure "value" : "37", // slot value has been changed to '37' "type" : "float", // slot data type is 'float' "path" : "/app/objects/EasyIO/ConstFl.set" // slot path }}

Due to a bug in appweb, the web server running on FG, we can not pass null valuedirectly. As a workaround, we need to use nil instead. CPT graphics server willconvert nil back to null before sending to svm.

invoke action without parameterFollowing is an example to invoke action without parameter, it is almost the same as aboveexample, but there is no value parameter and the value of type is void:

7


How to send Multi-Write commandThe Multi-Write command is very similar with above Single-Write command, instead of putcommand parameter inside data attribute directly, put the multiple write commands inside anarray named reqs, then put the array reqs inside data.

Multi-Write command for slot

Here is an example in javascript to send multiple write commands to server:

var url = 'http://192.168.10.11/sdcard/cpt/app/data_api.php';$.ajax({ url: url, type: 'POST', dataType: 'json', data: { reqs: [{ path: '/app/objects/EasyIO/Add2.in1', value: 100, type: 'float' }, { path: '/app/objects/EasyIO/And2.in2', value: 'false', type: 'bool' }] } }).done(function(data) { console.debug(data); });

If everything goes well, the response looks like this:

9

{ "response":{ "resultCode":0, "result":[ { "p":"/app/objects/EasyIO/Add2.in1", "t":"f", "v":"100" }, { "p":"/app/objects/EasyIO/And2.in2", "t":"b", "v":"false" } ] }}

for Multi-Wirte request, we will use the short format for attribute name and datatype value to save some space on server side, especially on svm side. Here is themapping between short name and full name:

Attribute:

Short Name Full Name

p path

t type

v value

DataType:

Short Name Full Name

b bool

c byte

s short

i int

l long

f float

d double

S Str

B Buf

10

Multi-Write command for action

And you can make a HTTP request with multiple action commands, too. Under this case, you mustset parameter is_action to 1. Here is an example in javascript:

var url = 'http://192.168.10.11/sdcard/cpt/app/data_api.php';$.ajax({ url: url, type: 'POST', dataType: 'json', data: { is_action: 1, ① reqs: [{ path: '/app/objects/EasyIO/ConstFl.set', value: 100, type: 'float' }, { path: '/app/objects/EasyIO/ConstBo.setTrue', value: '', type: 'void' }] } }).done(function(data) { console.debug(data); });

① this is MUST be set here

The response looks like this:

{ "response":{ "resultCode":0, "result":[ { "p":"/app/objects/EasyIO/ConstFl.set", "t":"f", "v":"100" }, { "p":"/app/objects/EasyIO/ConstBo.setTrue", "t":"void", "v":"" } ] }}

11

you can NOT mix slot/property write command with action command, only onetype of command allowed within one HTTP request.

Backup & Restore APIBy the Web API, you can do backup and restore, just like the backup & restore feature in CPTGraphics web page.

The handler URL for backup & restore is: CONTROLLER_IP/sdcard/cpt/app/utility.php. Followingsections will demo how to use the API. Although these examples use javascript, but any HTTP clientlibrary will work.

Fetch Backup ListTo fetch the current backups, the request looks like this:

var url = 'http://192.168.10.11/sdcard/cpt/app/utility.php';$.ajax({ url: url, type: 'GET', dataType: 'json', data: { action: 'list_backups' } }).done(function(data) { console.debug(data); });

The response looks like this:

{"backups": [ {"name":"20180525_backup","type":"sdcard","withNetworkConf":false,"ts":1527234432}, {"name":"my_backup","type":"flash","withNetworkConf":true,"ts":1527235735}]}

backups contains the list of all backups. for every backup element:

• name: backup’s name

• type: what type of storage the backup is stored at, either sdcard or flash

• withNetworkConf: if the backup contains network settings

• ts: the Unix timestamp when backup is made

Make New BackupTo make a new backup:

12

https://www.unixtimestamp.com/

{ "response" : { "resultCode" : -1, "errors" : [ { "errorCode" : 2, "path" : "/EasyIO/Ramp1", "description" : "Can't find component object" } ] }}

In the above example, sedona object with path /EasyIO/Ramp1 can not be found.

If value of resultCode is not 0, it means something goes wrong when fetching sedona object’s data.More detailed error information is stored in the errors array.

For every element in the errors array, there are 3 keys: errorCode, path, description. Currently, allerrorCode and description are defined like this:

errorCode Error Description

1 Invalid Path

2 Can’t find component object

3 Can’t find slot SLOT_NAME

4 URL SCHEMA custom is temporarily notsuppported

5 Invalid URL SCHEMA SCHEMA_NAME

6 COMPONENT_TYPE type custom component is notsupported

7 Slot type mismatch SLOT_NAME/SLOT_TYPE

8 slot not a property

9 slot not an action

10 Invalid value VALUE, SLOT_TYPE value expected

Due to memory limitation of sedona, easyioCpt kit can not handle URL that’s toolong. It will be a problem when requesting too many data points within onerequest. The solution is multiple requests, and make sure the url parameter inevery request’s URL shorter than 350 characters.

Update: if you are using easyioCpt later than v1.0.45.35.9(included), then theabove url limitation has been changed to 1024 characters.

16

How to set up demo scriptThe data_api_demo.html is simple demo that explains how to signin, fetching/modifying a slot’svalue. Please follow these steps to set it up on controller:

• ftp upload data_api_demo.html file to controller /mnt/appweb/web/public

• ftp upload jquery-1.10.0.min.js file to controller /mnt/appweb/web/public

• open 192.168.10.11/data_api_demo.html in browser

Examples

Change Controller’s DateTimeBy data api, you can change controller’s datetime. First, make sure a datetime service object(forexample, datetimeStd::DateTimeServiceStd) is available in sedona app. In the following codes,assume the object’s path is just /service/time.

To change datetime, there are possible several requests need to be sent:

• set property osUtcOffset (true or false)

• set property tz(timezone) text (timezone string, "America/New_York" etc)

• set property utcOffset value (how many seconds ahead of UTC time, can be negative)

• invoke action setSysClock with value of how many nanoseconds after 2000/01/01 00:00:00 UTC

So for example, to change controller’s datetime to 2014-11-20 22:37:00 of America/New_York

timezone, the requests looks like this:

17

http://192.168.10.11/data_api_demo.html

// change `osUtcOffset` mode to falsevar url = 'http://192.168.10.11/sdcard/cpt/app/data_api.php';var path = '/app/objects/service/time.osUtcOffset';$.ajax({url: url, type: 'POST', dataType: 'json', data: {path: path, type: 'bool', value: 'false', slotType: 'property'}});

// change 'tz' to 'America/New_York'var url = 'http://192.168.10.11/sdcard/cpt/app/data_api.php';var path = '/app/objects/service/time.tz';$.ajax({url: url, type: 'POST', dataType: 'json', data: {path: path, type: 'Buf', value: 'America/New_York', slotType: 'property'}});

// change 'utcOffset', since New York time is 5 hours behind UTC time,// so the value is 18000(5*60*60) and negativevar url = 'http://192.168.10.11/sdcard/cpt/app/data_api.php';var path = '/app/objects/service/time.utcOffset';$.ajax({url: url, type: 'POST', dataType: 'json', data: {path: path, type: 'int', value: '-18000', slotType: 'property'}});

// invoke 'setSysClock' with nanoseconds after 2000/01/01 00:00:00 UTCvar url = 'http://192.168.10.11/sdcard/cpt/app/data_api.php';var path = '/app/objects/service/time.setSysClock';$.ajax({url: url, type: 'POST', dataType: 'json', data: {path: path, type: 'long', value: '469856220000000000', slotType: 'action'}});

18

CPT Web API HowTo Document · 12/6/2018 · Introduction This Document will show you how to use...

Documents

Transcript of CPT Web API HowTo Document · 12/6/2018 · Introduction This Document will show you how to use...