Clients - Overview

Follow

Overview

The Exosite One Platform's underlying fundamental element is a 'client'.  Clients represent physical things like machines and devices but also represent users, application, and vendors.  The platform manages a database of client elements, their heirachy of ownership and their resources (data, rules, scripts, meta) in addition to providing access to the outside world for writing and reading data contained in them.

Starting on Device Client Software - Check List

Deploying Many Device Clients 

Client Characteristics

Clients have the following characteristics:

  • Have ownership of other clients or are owned by other other clients
  • Contain Resources such as data, rules, scripts, and dispatches
  • Has a RID and a CIK
  • Has meta information such as timezone or other info that is useful to User Applications
  • Has a friendly name
  • Has an 'Alias'
  • Has a visibility setting for owners
  • Has limits such as number of data ports
  • Has information kept about when it was created, updated, how many subscribers, counts of resources, storage, 
  • Has a activation status (client model types)
  • Has tags


Using these items and descriptions of a client, applications can present the client and data to a user to represent an actual physical thing, most typically a physical electronic device but could also represent an application running on a phone or computer or server, a user, or a company account.

 

Basic Client Use

The most typical use for a client is when code wants to write or read a data port (data source) for that client. Example is a device connected to the internet and has the ability to send a IP packet to a server.
In this case, the code needs to know the following information:

  • Exosite API (how and where to send the data)
  • The Client's CIK (Essentially a public key)
  • The Client's data-port's alias (Essentially a variable name) - For this example let's say it is 'temp'.

A mock write would be something like this: The device's code would open a connection to the Exosite server address documented in the API, send the data in the API format including the CIK so the One Platform could identify who was sending the data and where to put it, the data port's alias and it's value to write. The One Platform will receive this data value and place it into that data port's data store with a time-stamp from when it received it.

 

Hierarchy
This hierarchy tree of clients that make up the One Platform is architected for the use cases of the real world. Ownership of devices, data, sharing of data, and mapping a way that is extensible to an application is natively built in to the platform.  Clients can access clients and resources it owns but not above.  

What's inside of a single Client
A client in the One Platform is a single element that is mapped into the platform's catalog by it's RID. All information about this client is then found in a separate One Platform database. The RID is like a private key that locks away everything for this client. Once you start digging into the client, you'll find resources, meta data, etc.

Clients contain what are called 'Resources'.  Resources are things such as data ports, data rules which can be logical type or script, and dispatches.  Each resource has limits on time series data history.

Data Ports

Data ports are the resources that hold time-series data.  Clients can have many data ports and each data port's use may be different.  Some data may only be for information use like holding an email address of a contact and historical values are not important.  Other data may be for writing values to that are important to view at a later time for user interfaces.  Some data may be for transport protocols only and is quickly parsed into usable data and stored into other data ports.  

Data Ports can have value types of integer, string, and float.

Data Rules - Logical

Logical data rules are much the same as data ports as they contain time series data but their values are only 0 or 1.  They differ in that they have conditions in which they compare to subscribed data ports to decide if they are in the active (1) state or non-active (0) state.  Each change of state is recorded with a timestamp.

Scripts

Scripts are stored as data rules in the One Platform clients but instead of having a specific set of conditions, they contain a Lua script that has access to the clients other resources and has an API for accessing featurs on the One Platform.

More information on scripting can be found here.

Dispatches

Dispatch resources are used to communicate outside of the client and outside of using subscription data ports.  Instead dispatches use transports like Email, SMS, XMPP, and HTTP to push data externally from the platform.  Dispatches be be attached to logical data rules or used by scripts.  Dispatches store historical time series values for each dispatch and if it succeeded or not.

Meta

The Meta field is a single element of a client that typically holds a structured formatted string of data used by applications.  The Meta field does not hold time series data and is optional to use.

Note about Aliases

Clients can access it's own resources and owned clients by using either a direct RID (resource identifier) or by using an 'alias' for the resource or client.  An example alias for a data port resouce that is temperature data might be 'temp'.  As you can see it is essentially a variable name that API / Scripting can use instead of RIDs.  

Note about the CIK (Client Identifier Key)

Clients have a CIK that is assigned by the One Platform.  This CIK should be used for accessing API calls to the platform.  CIKs are mapped to the Client's RID.  CIK's are a 40 digit hexadecimal hash. More information on SHA-1.

 

Client Details
When a client is created, there are description settings that are provided such as a name, visibility level, meta information and limits. Once created, a client begins to take on other information, which is called 'Information', hopefully this diagram explains this a little better. Things such as the key (CIK) for this device, what subscribers it has (resources, other clients it owns), what are it's storage values, etc. Some of the APIs allow for creating, editing, and getting information about a client. The Exosite Portals web application is an example of code that uses the Exosite API to access this information about a client and allows users to create clients (Add Device).

Full Access to Client Information is available from the JSON RPC API and Scripting API

 

 

Client Description Fields

  • name
    • Format: String
    • Description: This is a friendly name, essentially meta data
  • visibility
    • Options: "ancestor" | "clone" | "parent" | "private" | "public" = "public"
    • Default: "public"
    • Description: Controls what level of owner clients can see this client
  • writeinterval
    • Format: Number
  • meta
    • Format: String
    • Description: Typically used by applications to hold descriptive information about a client. The platform does not use any of this information. Example, a web application may track timezone in this meta field to properly show device location time on data. The Exosite Portals web application uses a specific set of data in a JSON format and should be complied with in order to use with-in that tool. 
  • limits
    • Format: Number(s)
    • Description: These are limits on the number of resources the client can have. Can be used to make sure a client does not go over a required value for an application.
    • Fields: (Note: a value of 0 = 'inherit from owner')
      • client, dataport, datarule, disk, dispatch, email, email_bucket, io, share, sms, sms_bucket, xmpp, xmpp_bucket


Client Information Fields

  • aliases
    • Format: An array of Aliases (Strings)
    • Description: The list of aliases for a Client
  • basic
    • created
      • Format: Number
      • Description: Timestamp when client was created (UTC Unix Timestamp)
    • modified
      • Format: Number
      • Description: Timestamp client was last modified (UTC Unix Timestamp)
    • subscribers
      • Format: Number
      • Description: Number of subscribers to this client
    • type
      • Options: "client" | "dataport" | "datarule" | "dispatch"
      • Description: The type of resource this is, which for a client will always be 'client'.
  • counts
    • Format: Number(s)
    • Description: 
    • Fields: 
      • client, dataport, datarule, disk, dispatch, email, io, share, sms, xmpp
  • key
    • Format: CIK (40 Character Hash)
    • Description: Holds the CIK (Client Identifier Key) for the client
  • shares
    • Format: Array of shares that include RID, share code, and description (String)
    • Description: Stores all share codes used by Client
  • storage
    • count
      • Format: Number
    • first
      • Format: Number
    • last
      • Format: Number
    • size
      • Format: Number
  • subscribers
    • Format: Array of subscribers that include type of resource and RID
    • Description: Stores all subscribers for the Client
  • tags
    • Format: Array of tags (String)
    • Description: Stores all tags for the Client
  • usage
    • Format: Number(s)
    • Fields: 
      • client, dataport, datarule, disk, dispatch, email, io, share, sms, xmpp

 

Further Reading

Deploying Many Device Clients as a Client Model

Client Scripting Interface

 

 

Have more questions? Submit a request

Comments

Powered by Zendesk