This site has been deprecated. Do not edit pages here. Please visit the new Pico Labs documentation.


Skip to end of metadata
Go to start of metadata
Draft Specification

This specification and the associated services are currently drafts under development.

This is a strawman for discussion and demonstration purposes.

We anticipate that this interface will change substantially as it moves toward a production release.

The CloudOS service provides fundamental interaction points (APIs) for managing personal cloud account services. This includes the ability to manage personal clouds, personal channels, and rulesets within personal clouds. To be used, the CloudOS service must be installed in the personal cloud. In addition, any rulesets that use the CloudOS service must reference it as a module:

Should the API key be in the keys section and should the module take them through configuration?

We will discuss the following:

  • Managing personal clouds
  • Managing personal channels
  • Managing rulesets

 

Ed Orcutt has created sample rulesets that use the CloudOS service that are available on Github.

 

Managing Personal Clouds

Sometimes, one personal cloud needs to manage another. For example, a ruleset managing the physical assets of a cloud's owner might need to create a new cloud for a new asset or destroy an existing one when the asset is disposed of.

Why are these function interfaces instead of event interfaces? Not saying they should be, but trying to understand/convince myself. Why are there event interfaces for the others, but not clouds?

The following functions are available:

cloudCreate(email, password, apikey)

The cloudCreate() function will create a new personal cloud with the email address and password provided. Upon successful creation of the new Personal Cloud the CloudOS Ruleset will be installed into the new Personal Cloud.

Note: To obtain a developer apikey please contact edo@kynetx.com

If we modify accounts so that there is a one-to-many mapping between an account and clouds it controls, then we could get away from having to have a password. Instead, the CloudOS service could authorize (OAuth) to the account and then perform these functions.

The function will return a JSON structure as follows:

{
"status" : true,
"token" : "27329425-d750-992a-cc15-zz163e3d039d",
"msg" : "Authentication Successful"
}

Upon successful creation of the new personal cloud, status will be true, otherwise status will be false. In addition, token will return an event channel identifier for the newly created personal cloud. Upon successful creation the CloudOS ruleset will be installed into the new personal cloud.

The following example shows the use of cloudCreate() to create a personal cloud. 

cloudAuth(email, password)

The cloudAuth function can be used to authenticate with an existing personal cloud. Upon successful authentication to the personal cloud the CloudOS ruleset will be installed into the new personal cloud if it is not already there.

The function returns a JSON structure as follows:

{
"status" : true,
"token" : "27329320-d750-992e-cc15-zz163e3da64d",
"msg" : "Authentication Successful"
}

Upon successful authentication status will be true, otherwise status will be false. In addition, token will return an event channel Identifier for the authenticated personal cloud.

Managing Personal Channels

Personal clouds often need new channels. The following interface provides for managing the channels in a personal cloud. There are both functional and event-based interfaces for managing channels.  

Functions

channelCreate(channelName, userToken)

The channelCreate() function will create a new personal event channel in the personal cloud identified by userToken, if specified. Otherwise the channel will be created in the current personal cloud.  The channelName will simply be a label for you to identify the purpose of the channel. The function will return a JSON structure as follows:

{
"status" : true,
"token" : "27329444-d750-992e-cc15-zz163ea6439d",
"msg" : "ECI creation Successful"
}

Is the userToken an ECI? If so, does this mean I can create a new channel on any PC I have an ECI into? If not, then we need to distinguish between tokens and ECIs. You use token when you mean ECI and I'm not sure which is which or if they're the same.

If this is an auth token/shared secret, then we ought to require it, even for current PC.

Upon successful creation of the personal channel the value of status will be true, otherwise status will be false. In addition, token will return the newly created event channel identifier.

The following code shows the use of createChannel():

Can we put authToken in keys? Is it managed programatically?

channelDestroy(channelID, userToken)

The channelDestroy() function will delete an existing personal channel for the personal cloud associated with the specified userToken, if specified. Otherwise the channel will be deleted from the current personal cloud. The function will return a JSON structure as follows:

{
"status" : true,
"msg" : "ECI deletion Successful"
}

Upon successful deletion of the personal channel the value of status will be true, otherwise status will be false.

The following code demonstrates the use of channelDestroy():

channelToken or eci?

channelList(userToken)

The channelList() function will retrieve a list of all of the personal channels available within the personal cloud associated with the specified userToken, if specified. Otherwise the list will be for the current Personal Cloud. The function will return a JSON structure as follows:

{
"valid" : true,
"channels" : [
{
"name": "Login_Token",
"cid" : "27329435-d750-012e-cc15-00163e3d03zz"
},
{
"name": "ReadOnly",
"cid" : "27329435-d750-012e-cc15-00163e3d03xx"
},
]
}

Upon successful completion the value of status will be true, otherwise status will be false.

The following code demonstrates the use of channelList():

Events

Channels can also be managed by event. The CloudOS service listens for the following channel-related events:

No auth token for these?

Create a Channel

Create a new Personal Channel within a Personal Cloud.

Event:

  • domain: system
  • type: channelCreate
  • attributes: 
    • channelName - The channelName should be bound to an identifier that conveys the purpose of the personal channel being created.

The following code shows how the system:channelCreate event can be raised:

The _api attribute ensures that this event will be raised with the Sky event API so that it is seen by other rulesets installed in the personal cloud.

Delete a Channel

Delete an existing channel within a personal Cloud.

Event:

  • domain: system
  • type: channelDestroy
  • attributes: 
    • channelID - The channelID must be an existing channel GUID within the personal cloud.

What is a channel GUID?

The following code sample shows how the system:channelDestroy event can be raised:

List Channels

Retrieve a list of all channels within a personal cloud.

How can you "retrieve" something by firing an event? I don't get what this does...

Event: 

  • domain: system
  • type: channelList
  • attributes: none

Managing Rulesets

A personal cloud needs to manage its own rulesets and the rulesets of clouds that it controls. 

There are both functional and event-based interfaces for managing rulesets.  

Functions

rulesetAdd(rulesetID, userToken)

The rulesetAdd() function will install a ruleset in the personal cloud associated with userToken, if specified. Otherwise the ruleset will be installed in the current personal cloud. Upon successful installation of the ruleset the function will return true, otherwise false will be returned.

The following code sample shows rulesetAdd() in use:

rulesetRemove(rulesetID, userToken)

The rulesetRemove() function will uninstall a ruleset from the personal cloud associated with userToken, if specified. Otherwise the ruleset will be removed from the current personal cloud. Upon successful removal of the ruleset from the personal cloud, the function will return true, otherwise false will be returned.

The following code sample shows rulesetRemove() in use:

rulesetList(userToken)

The rulesetList() function will retrieve the list of all rulesets installed the the personal cloud associated with userToken, if specified. Otherwise the list will be for the current personal cloud. The function will return a JSON structure as follows:

{
"valid" : true,
"rids" : [
{
"name": "PersonalBlock",
"rid" : "a169x230"
},
{
"name": "CloudOS",
"rid" : "a169x625"
},
]
}

Upon successful completion the value of valid will be true, otherwise valid will be false.

Why valid instead of status?

The following code sample shows rulesetList() in use:

Events

Rulesets can also be managed by event. The CloudOS service listens for the following ruleset-related events:

No auth token for these?

Install a Ruleset

Install a new ruleset into a personal cloud.

Event:

  • domain: system
  • type: rulesetAdd
  • attributes: 
    • rulesetID - The rulesetID must be a valid Kynetx ruleset identifier (e.g. a169x22).

The following code sample shows system:rulesetAdd being raised:

Uninstall a Ruleset

Uninstall a ruleset from a personal cloud.

Event:

  • domain: system
  • type: rulesetRemove
  • attributes: 
    • rulesetID - The rulesetID must be a valid Kynetx ruleset identifier (e.g. a169x22).
The following code sample shows system:rulesetRemove in use:

List the Rulesets

Retrieve a list of all of the rulesets installed in a personal cloud.

 

How can you "retrieve" something by firing an event? I don't get what this does... 

Event:

  • domain: system
  • type: rulesetList
  • attributes: none
Labels: