XMPP - Chat v0.2

Overview

This document specifies the One Platform’s XMPP Commander version 0.2 interface “command set”.

The Commander is a XMPP Bot which allows any authenticated XMPP client (typically a remote user) to initiate a XMPP Chat in order to issue commands to the One Platform through the Commander.

The Commander interfaces to the One Platform on behalf of the connected client. Given sufficient access rights the client may perform some or part of the following functions through the Commander:

• Read and write client resource values
• Create, delete and list Data Sources for client resources
• Count and read Data Source records

Command Set

Common Responses

When an XMPP Chat session is started with the Commander, all commands will receive a response.

If a command fails for any reason, the bot replies with an error message in the format of:

error: <reason>

If a command is successful the bot will reply with ok or the command specific response value.

Common Success Responses

ok

Common Error Responses

error: no identity

error: invalid parameters

error: unavailable

error: not implemented

Commander ID String

Gets the ID string of the running XMPP Commander instance.

Format

commanderid

Parameters

NA

Response

Replies with the bot name and version string.

XMPP Commander 0.2

Notes

It is not necessary to start a chat session to send this command. It may be sent in either a XMPP Chat or XMPP Message body.

Examples

Client:

commanderid

Bot Reply:

XMPP Commander 0.2

API Version

Gets the version number of the running XMPP Commander instance.

Format

version

Parameters

NA

Response

Replies with the version string.

0.2

Notes

It is not necessary to start a chat session to send this command. It may be sent in either a XMPP Chat or XMPP Message body.

Examples

Client:

commanderid

Bot Reply:

0.2

Help

Lists commands and help command syntax.

Format

help [<command>]

Parameters

<command> : Specifies the command to get help information for. Optional

Response

Replies with help information.

Notes

It is not necessary to start a chat session to send this command. It may be sent in either a XMPP Chat or XMPP Message body.

Examples

Client:

help

Bot Reply:

Type ‘help ‘ where is one of: commanderid, dscount, dscreate, dsdelete, dslist, dsread, dswrite, help, read, setcik, version, write

Client:

help dswrite

Bot Reply:

Write historical data to the named Portals Data Source

dswrite <alias> <timestamp> <value>

Set Client Interface Key

Sets the Client Interface Key (CIK) to the specified value. Setting the CIK starts a chat session. Chat sessions timeout after 5 minutes of inactivity.

Format

setcik <value>

Parameters

<value> : Specifies the Client Interface Key to identify to the One Platform as.

Response

See Common Responses

error: invalid key

Notes

REQUIRED This command is required. It must be the first command sent, else all other commands will fail.

Ensure your client is using an encrypted connection. Otherwise, your private Client Interface Key will be exposed to third parties and potentially exploited.

The CIK identifies the client to the One Platform. Certain commands may not be available depending on the access rights associated with the given CIK.

Examples

Client:

setcik 19cbdefad0b8e90b4d691376d5997f04c1acc18e

Bot Reply:

ok

Write Value

Sends a data value for a specific client resource to the One Platform for storage and processing.

Format

write <alias> <value>

Parameters

<alias> : Specifies the client resource identifier.

<value> : Gives the data value to write.

Response

See Common Responses

error: duplicate timestamp

Examples

To post the value 1043 for resource 1

Client:

write 1 1043

Bot Reply:

ok

Read Value

Reads up to the last 24 hours of written values for the specified client resource.

Format

read <alias> [<count>]

Parameters

<alias> : Specifies the client resource identifier.

<count> : Specifies the maximum number of data points to return, beginning at the most recent to the least recent. Defaults to 1. Optional

Response

The unix timestamp and value of the most recent data points will be returned in CSV format.

<timestamp>,<value>

Examples

Client:

read 1

Bot Reply:

1267806955,1043

Create Data Source

Creates a Data Source having a <name> for the <alias> to be stored. The <format> of the data source may be specified. Before storing a reported value, the value may be normalized with an <operation> of ‘add’, ‘sub’, ‘mul’, ‘div’ or ‘mod’ using the given <constant> value. To store data values without normalization, specify ‘na’ for <operation>.

Format

dscreate <name> <alias> [<operation> <constant> <format>]

Parameters

<name> : Specifies the friendly name of the Data Source to create.

<alias> : The resource identifier used when reporting data from the client.

<operation> : Specifies the normalization operation to be used. Defaults to ‘na’. Optional

• add : Add <constant> to <value> and store the result.
• sub : Subtract <constant> from <value> and store the result.
• mul : Multiply <value> by <constant> and store the product.
• div : Divide <value> by <constant> and store the quotient.
• mod : Divide <value> by <constant> and store the remainder.
• na : Store <value> without normalization.

<constant> : A number which to apply to <value> using the given <op>. Ignored if <op> is ‘na’
<operation> : Specifies the storage format of the data. Defaults to ‘float’ if ‘op’ is specified, otherwise defaults to ‘string’. Optional

• integer
• float
• boolean
• string

Response

See Common Responses
error: invalid or duplicate data source
error: too many data sources

Examples

Client:

dscreate “office temp” temp div 20

Bot Reply:

ok

Client:

dscreate Temperature 1 mul 5 integer

Bot Reply:

ok

Delete Data Source

Deletes the specified Data Source and all associated data. Caution!

Format

dsdelete <alias>

Parameters

<alias> : Specifies the resource identifier of the Data Source to delete.

Response

See Common Responses

error: invalid data source

Examples

Client:

dsdelete temp

Bot Reply:

ok

Write Data Source

Write data records to the Data Source identified by <alias> and timestamp <timestamp>.

Format

dswrite <alias> <timestamp> <value>

Parameters

<alias> : Specifies the resource identifier of the Data Source to write to.

<timestamp> : Specifies the unix timestamp to index the data by.

<value> : Gives the data value to write.

Response

See Common Responses

Examples

Client:

dswrite temp 1300777704 1067

Bot Reply:

ok

Read Data Source Records

Reads historical data records from the Data Source identified by <alias>.

Format

dsread <alias> <count> [<start> [<end>]]

Parameters

<alias> : Specifies the resource identifier of the Data Source to read from.

<count> : Specifies the maximum number of data records to return, beginning at the most recent to the least recent.

<start> : Specifies the earliest unix timestamp for which to retrieve historical data records. Optional

<end> : Specifies the latest unix timestamp for which to retrieve historical data records. Optional

Response

If successful data records of unix timestamp and data value pairs are returned in CSV format.

<timestamp>,<value>

<timestamp>,<value>

…

Examples

Client:

dsread temp 3

Bot Reply:

1300796584,52.7
1300796577,52.15
1300777704,53.35

List Data Sources

Lists all created Data Sources.

Format

dslist [<detail>]

Parameters

<detail> : Specifies the detail level of the list to return. Defaults to ‘name’. optional

• name : Returns the Data Source name only.
• full : Returns the Data Source name, resource, operation, and constant values.

Response

A list of Data Source names are returned in CSV format.

<name>,<resourceid>,<operation>,<constant>

<name>,<resourceid>,<operation>,<constant>

…

Examples

Client:

dslist

Bot Reply:

office temp

office humidity

outside temp

outside humidity

Client:

dslist full

Bot Reply:

office temp,1,div,20

office humidity,10,div,100

outside temp,2,div,20

outside humidity,11,div,100

Count Data Source Records

Counts the number of historical data records from the Data Source identified by <alias>.

Format

dscount <alias> [<start> [<end>]]

Parameters

<alias> : Specifies the resource identifier of the Data Source to count records from.

<start> : Specifies the earliest unix timestamp for which to start counting historical data records. Optional

<end> : Specifies the latest unix timestamp for which to end counting historical data records. Optional

Response

The number of historical records that exist in the range specified. If no range is given, then all records are counted.

Examples

Client:

dscount temp 1300777704 1300796584

Bot Reply:

3