Site Tools


proposal_for_iotivity_smart_home_api

IoTivity Smart Home API

This is a contribution proposal about IoTivity Smart Home APIs to implement IoTivity services more intuitively.

Problem Definition

  • Lack of consideration in view of API usability
    • Not easy to understand
      • Uncalssified APIs in ocstack.h
    • Not easy to use
      • Need to know specification
      • Non-intuitive Logical-level operation

Concept

  • Usability-improved API
    • Device-level operation
    • Client/Device-side separated API
    • Spec-agnostic API

Features

  • Smart Home Device/Resource Layer for devices in OCF Smart Home Specification
  • Smart Home Base Device/Resource Layer required minimum-spec knowledge.
  • DeviceBrowser that provides device-level discovery.

Advantage

  • Device-side
    • Easy way to make new device app.
      • Pre-implemented Smart Home Device/Resource class
        • Light,SmartLock/BinarySwitch,LockStatus
      • Base Device/Resource class
    • Easy way to response
      • Automatic response
  • Client-side
    • Easy way to make new client app.
      • Pre-implemented Smart Home Remote Device/Resource class
        • RemoteLight,RemoteSmartLock/RemoteBinarySwitch,RemoteLockStatus
      • Base RemoteDevice/Resource class
    • Easy way to send request data
      • Set/get property-level
  • Common-side
    • Separated callback handling
      • OOP-style callback (decoupling)
    • Light-weight api to deploy
      • No boost, No c++11

Class Diagram

  • Client-side

  • Device-side

  • Common-side

Examples

1. Device-level discovery

int main(int argc, char* argv[]) {
    DeviceBrowser browser = DeviceBrowser::getInstance();
    browser.setDelegate(&delegate);
    
    BrowseQuery query;
    query.setDeviceType(DEVICE_LIGHT);
    
    browser.findRemoteDevices(query);
}

2. Predefined device/client

1) Make predefined device

Light myLight;
MyBinarySwitchDelegate switchDelegate;
myLight.m_binarySwitch.setDelegate(switchDelegate);

2) Make predefined client

//after finding devices
...
if (DEVICE_TYPE::LIGHT == remoteDevice->getType())
{
...
     m_light = (RemoteLight*)remoteDevice;
     m_light->m_remoteBinarySwitch->setDelegate(delegate);
     m_light->m_remoteBinarySwitch->getState();
     ...
     m_light->m_remoteBinarySwitch->on();
}

3) Handling request and response

//Client-side
class MyDelegate : public RemoteBinarySwitchDelegate
{
    void onTurnOn(ResultCode code){...}
    void onTunOff(ResoutCode code){...}
    void onGetStatus(string state, ResoutCode code){...}
}

MyDelegate delegate;
light.switch.setDelegate(delegate);
light.switch.on();

//Device-side
Light light();
MyDelegate* delegate;
light.setDelegate(delegate);

class MyDelegate : public BinarySwitchDelegate
{
    ResultCode onTurnOn(){
        return SUCCESS;
    }
    ResultCode onTrunOff(){
        return SUCCESS;
    }
}

3. New device/client

1) Make new device

// New Color Resource Class Declaration.
class OCFColorResource : public Resource
{
public:
    OCFColorResource();
    virtual ~OCFColorResource();

    void setColorDelegate(OCFColorDelegate* delegate);
};

// Extended Light Device Class Declaration.
class OCFLight : public Light
{
public:
    OCFColorResource m_color;
};

// Create Light Device
OCFLight *myLight = new OCFLight;

2) Make new client

// New Color Resource Class Declaration.
class OCFRemoteColorResource : public Resource
{
public:
    void setColorDelegate(MyColorDelegate*delegate);
    void changeColor(std::string color);
    void getState();
};

// Extended Light Device Class Declaration.
class OCFRemoteLight : public RemoteLight
{
public:
    OCFRemoteColorResource *color;
};

3) Handling request

// Callback Class Impl to handling request.
class OCFColorDelegate : public ResourceDelegate
{
    ResultCode onGet(int requestId, const PropertyBundle& bundle);
    ResultCode onSet(int requestId, const PropertyBundle& bundle);
};

class OCFBinarySwitchDelegate : public BinarySwitchDelegate
{
    ResultCode turnOnCallback();
    ResultCode turnOffCallback();
};

// Set Callback class to receive request message.
OCFLight *myLight = new OCFLight;

OCFBinarySwitchDelegate *switch = new OCFBinarySwitchDelegate;
myLight>m_binarySwitch.setDelegate(switch);

OCFColorDelegate *color = new OCFColorDelegate;
myLight->m_color.setDelegate(color);

4) Handling response

// Callback Class Impl to handling response.
class OCFRemoteBinarySwitchDelegate : public RemoteBinarySwitchDelegate
{
    void onTurnOn(ResultCode ret);
    void onTurnOff(ResultCode ret);
    void onGetState(bool value, ResultCode ret);
};

// Set Callback class to receive response message.
OCFRemoteBinarySwitchDelegate *switch = new OCFRemoteBinarySwitchDelegate;
remoteLight>m_remoteBinarySwitch.setDelegate(switch);

// Send get request to remote device.
remoteLight->m_remoteBinarySwitch->getState();

// Send post request to remote device.
remoteLight->m_remoteBinarySwitch->off();
remoteLight->m_remoteBinarySwitch->on();

More things

For this proposal, we will also consider following features that provide efficient processing in Smart Home environment and more usability when app developers make services on IoTivity.

  • Multi-threaded Processing RI
    • handling requests and responses in parallel.
  • Separated APIs in C API
    • Need to sperate apis in ocstack.h file as each files that have a role such as Client-side, Server-side, Client and Server-side, …
  • Self S/W Recovery
    • Need to recover data for client and server when restarting their service.
      • observe information in each side for continous observing.
  • and more..
proposal_for_iotivity_smart_home_api.txt · Last modified: 2017/04/14 06:54 by glen.kim