Kadecot APIs overview

Sony Computer Science Labs, Inc.

Kadecot API

Shigeru Owada Sony Computer Science Labs, Inc.

Japanese version API description: http://kadecot.net/webapi/

http://kadecot.net/webapi/

http://kadecot.net/webapi/

Sony Computer Science Labs, Inc. Sony Computer Science Labs, Inc.

Summary

• This slide describes the introduction of the Kadecot Web API (http://kadecot.net)

Enables JavaScript access for ECHONET Lite devices/sensors, (some) Sony devices, IRKit etc. Available on Google Play Open source (MIT License) https://github.com/SonyCSL/

Other protocols can be easily added by developing “Plugins”

Basic functions

●Get device lists ●Deliver commands to devices ● Obtain device status ● Notification on device state changes

API server Kadecot

（ka-de-co）

http://kadecot.net/

https://github.com/SonyCSL/




Two kinds of APIs

• JSONP API – Easy

– Slow (Disconnect on every access)

– Cannot receive notification from devices (Polling necessary)

• WebSocket API – Fast (Constant connection)

– Receives asynchronous notifications

– Requires basic knowledge of WAMP


JSONP API

• JSONP : abbrev. of “JSON with Padding” – HTTP-based remote function call without cross-origin issues – Commands and parameters are URL-embedded.

• Can test on a web browser’s URL field

• To enable, just select ‘Developer mode’ in the Kadecot

settings page.

• No security. No access restrictions. ⇒Should only be used for testing purposes. The users should be careful not to forget turning off the developer mode

• JSONP access is essentially the RPC access of the WAMP API (described later)


JSONP for ECHONET Lite

• List http://[Kadecot IP]:31413/jsonp/v1/devices/

• Set http://[KadecotIP]:31413/jsonp/v1/devices/[Device ID] ?procedure=set &params={"propertyName":“OperationStatus","propertyValue":[0x30]}

• Get http://[KadecotIP]:31413/jsonp/v1/devices/[Device ID] ?procedure=get &params={"propertyName":“OperationStatus"}

+DeviceIDs are displayed on the device icons in Kadecot

+ECHONET Lite supports set/get for procedures but other protocols have different sets of procedures


Two kinds of APIs

• JSONP API – Easy

– Slow (Disconnect on every access)

– Cannot receive notification from devices (Polling necessary)

• WebSocket API – Fast (Constant connection)

– Receives asynchronous notifications

– Requires basic knowledge of WAMP


WebSocket API

• WebSocket is a JavaScript socket supported by major web browsers – Standard socket with handshaking.

• After handshaking, it works as a standard socket.

• We use WAMP on top of WebSocket – WAMP: A protocol that defines the

communication protocol between Web apps

– http://wamp.ws

UDP

WebSocket

WAMP

Kadecot WebSock

API

http://wamp.ws/


Overview of WAMP messaging

RPC pattern • The information is supplied by

the callee (device) for each caller request.

• Suitable for on-demand information delivery or retrieval

• Conceptually equivalent to JSONP API

PubSub pattern • The publisher (device)

spontaneously transmits information at arbitrary times

• The subscribers (Web Apps) subscribes for information and receives the notifications

• Suitable for monitoring changes in devices

Caller

Callee

Cal

l

Rep

ly

Subscriber

Publisher

Sub

scri

be

in

ad

van

ce

Asy

nch

ron

us

No

tifi

cati

on

s (P

ub

licat

ion

)

WebSocket API Initialization <!-- read libraries <script type="text/javascript" src="http://app.kadecot.net/js/wamp-client.min.js"></script> <script type="text/javascript" src="http://app.kadecot.net/js/wamp-client-browser.js"></script> <script> onload=function(){ //↓ Create WAMP object (should be stored for later use) var wampClient = new WampClientBrowser() ; //↓ Definition of callback for successful connection wampClient.addOpenCallback(function(){ //↓ Send Hello message by WAMP wampClient.sendHello("default", {"roles":{"caller":{},"subscriber":{}}}, function(){ // request device list //↓ If Hello succeeds, send request for device list wampClient.sendCall({}, "com.sonycsl.kadecot.provider.procedure.getDeviceList“ , null, null, function(ret){ console.log('Devlist reply! : '+JSON.stringify(arguments)) ; //var ds = ret[4].deviceList ; }); } ) ; } ) ; //↓ Start connection wampClient.connect("ws://[KadecotIP]:41314/"); } ; </script>


RPC call example

// Example for obtaining the device list wampClient.sendCall( {} , "com.sonycsl.kadecot.provider.procedure.getDeviceList“ , null , null , function(ret){ var ds = ret[4].deviceList ; } ); // Send power on (0x30) for deviceId #1 wampClient.sendCall( {"deviceId":1} ,"com.sonycsl.kadecot.echonetlite.procedure.set" ,[] ,{"propertyName":"OperationStatus","propertyValue":[0x30]} ,function(){} );

Use wampClient.sendCall() for RPC

↓Procedure string (the name of remote function)

←Callback function to obtain the result

←No argument for this procedure

←Procedure

（Callback function to receive the response. Not used in this case） ←Argument

←Target device


PubSub call example

• The target information to subscribe is called “Topic”.

• Just supply the desired topic and callback functions in sendSubscribe()

• Note that a topic is NOT defined for each instance of a device, but rather for the type of property.

• Therefore, publication from undesired devices should be filtered out by checking the device id.

wampClient.sendSubscribe( {} ,"com.sonycsl.kadecot.echonetlite.topic.HomeAirConditioner.OperationStatus" ,function(r){ console.log('Value changed :’+JSON.stringify(r)); if( r[4].deviceId != 1 ) return ; } ,function(){ console.log('Subscribed : '+JSON.stringify(arguments)); } ;

// ↓ Topic

// Callback 1: called every time when the device publishes

// Callback 2: called only once when sendSubscribe() call succeeds

// exclude undesired devices

Use wampClient.sendSubscribe() for PubSub


Reference 1

This page shows available property names of ECHONET Lite devices, though property names can be replaced by EPC numbers, as described in the ECHONET Lite official spec sheet. Eg. “OperationStatus” == “0x80” Currently, PubSub is implemented only for ECHONET Lite EPCs where notification is mandatory.

http://app.kadecot.net/docs/ProcTopic/




Reference 2

• API tool API tool helps generate API call strings for existing devices

• This tool is listed as an official web application of Kadecot

• Can also be accessed from the following URL (supply Kadecot IP address as the URL argument “kip”)

http://app.kadecot.net/Apps/APITool/?kip=[Kadecot IP]


Reference 3: Open sources • KadecotCore + ECHONET Lite Plugin (MIT License)

– Kadecot source code

• OpenECHO for Java / C++ （MIT License） – A device driver for ECHONET Lite

• ECHONET Lite - Object Database （CC0：Public domain）

– ECHONET Lite devices database as CSV – Used for generating the Java OpenECHO class library – Release C

• MoekadenRoom （MIT License）

– ECHONET Lite emulator for PC – http://kadecot.net/blog/1479/

Released on https://github.com/SonyCSL/

http://kadecot.net/blog/1479/

http://kadecot.net/blog/1479/





Thank you http://kadecot.net/ http://moekaden.com/

@kadecot_dev @moekaden

http://kadecot.net/

http://moekaden.com/

Kadecot APIs overview

Technology

Transcript of Kadecot APIs overview