Exosite FAQs

In our ongoing effort to continue improving the Murano Customer Experience, Exosite has released an update to our platform account administration UI ( https://exosite.io ). It is important to note that there are no changes to existing accounts in regards to billing or service. This update is entirely a user interface improvement to help the user experience with organization, ease of use, and clarity of information.

A summary of the updates to the Exosite Account Administration area:

The Solutions page will now be called Home and is organized into different sections.

What were formerly called Product solutions are now referred to as IoT Connectors.

Custom Application solutions are now referred to as Murano Applications.

The IoT Exchange marketplace has an improved user interface and organization

Weve updated Exchange to reflect our focus on enabling our vertical solutions such as ExoSense and related elements such as Insight services and third-party IoT Connectors for off the shelf hardware.

We have additional exciting improvements planned over the next few months and will continue to keep you informed. Additionally, our Customer Success team is available to discuss these updates and options. If you have any questions or feedback at this time, please contact your Exosite Customer Success team member or [email protected].

In our previous One Platform maintenance update regarding the change of trusted root certificate for clients connecting to m2.exosite.com domain, we updated all assigned vendor domains to use the new trusted root certificate. As a continuation of that effort, the trusted root certificate for clients not using their assigned vendor domain will be changed to the same root certificate as the assigned vendor domains.

The new DigiCert Global Root CA (November 10, 2031, 12:00:00 AM GMT) certificate chainwill be served per the following schedule (all times UTC):

June 3, 14:00 - 16:00

June 4, 14:00 - 16:00

June 6, 02:00 - 06:00

June 6, 14:00 - 18:00

On June 10 at 14:00 and after, the m2.exosite.com domain will serve the new "DigiCert Global Root CA" root certificate.

Please update all client implementations to use their assigned vendor domain before June 3rd in order to maintain connectivity to the One Platform without interruption.

This notice is only for One Platform connectivity.

Murano connectivity is not affected.

If you have any questions please contact our support team: [email protected]

This is a guide for developers looking to create device client software (firmware, code) and useExosite Platform / Portals to ensure a positive out-of-box experience for your products, kits, demos, etc.

Reference Code

Exosite provides libraries and many reference projects for device application and firmware that may jumpstart your own code project. Review theavailable Device SDKs, Libraries, and hardware platform reference code..

Getting started notes / check list:

Learn about what clients are, which represent devices in the Exosite One Platform.

Decide on what API to use.

Use DNS URLs (like m2.exosite.com). Do not hard codeserver ip addresses for the API calls. Servers can and will change, IP addresses are not always guaranteed to stay. Be sure that devices check DNS more than just at boot up, whether on a recurring time period check or with exception handling when it can't connect to the server. Devices in the field may not have the ability to be reset / re-powered on to get the new IP Address through DNS.

Make sure to think through how you will handle different response codes from the server for retries, detecting bad network connections, and bad Exosite authorization (CIK).

You may want to start with hard-coded client identifier keys (CIK) which are used as a key to talk to the API. Once functionality is there for using the API (read, write, etc) implement provisioning with vendor client models so devices can automatically receive a CIK for large deployments. To get a hard-coded CIK, add a 'generic' device to your account.

Think about how users can identify the state of the devicein regards to connecting to the network and to Exosite. Example, using flashing LEDs to report connection status or error conditions.

Create a Data Architecture.

What data does the device need, what data does the UI need, what data do you as the device vendor need?

What is the format of that data. Is it individual streams of integers, floats, or strings? Is it formatted data like JSON or XML or CSV?

Will there be scripts that need to be created to process, analyze, or send out dispatches?

Basic Write and ReadFunctionality

Decide what data the device needs to send to and read from the cloud. These are called dataportsin the platform and may also be referred to as data sourcesor data streams.

Recommended APIs to get basic support forwrite / read functionality:

https://github.com/exosite/api/tree/master/data (HTTP POST / GET)

https://github.com/exosite/api/tree/master/coap (COAP)

Decide how the device client code will get the Client Identifier Key (CIK) to access the API. If you arenot using a Vendor / Client Model Type (Exosite sub-domain Whitelabel Vendor account), you should assume users will create ageneric device type. For generic devices,copyCIK manually into the code on the device, which you can find in the portal by going to the Devices manage page and clicking on your device.

(We recommend using a Whitelabel account to create your own Client Model instead - see below for additional information).

Troubleshooting HTTP Messages

Most developers start using our HTTP Data interface, using POST and GET methods. If you'd like an example of putting together one of these HTTP messages, this example script is a good reference. It's python but shows using TCP socket, not a HTTP library. So, it is useful for reference even if using C code for example.

https://github.com/exosite-garage/utility_scripts/blob/master/http_https_data_interface_read_write_socket_example.py

Of course if you have python on your computer you can quickly test this with your own CIK and data source alias.

Advanced APIFunctions

TheRPC API allows for more advanced functionality beyond read/writefrom the device, includingrecording (logging data),creatingsub-devices (nodes),editingthe device client's setup on the platform, and callingmultiplefunctions in one request. The RPC is available over HTTP in JSON format or over CoAP in CBOR format.

http://docs.exosite.com/rpc/

UseCloud Scripting Engine

Add Platform Scripts to your devices in the Exosite One Platform which can perform processing of data, analytics, and alerting.

parsing raw data

sending out alerts

detection of device status, whether it is online

manipulate the data for user interfaces

These next items require Vendor accounts

Client Models / Device Activation(vendor accounts)

Client Models represent a product line or fleet. Vendors accounts can create client models, which are essentially a profile that is cloned each time a device is added to the account, but also give the vendor fleet management functionality. The use of client models requires devices to 'activate' as a specific unique device under that client model.

Use the Provisionin g API on the device so that it activates as a specific Client Model (specific product). This also allows a device to connect to the platform without having to have a CIK manually programmed into it, allows a device to get content updates, and allowsyou to manage each specific device's access. Provisioning is available for devices using either HTTP or CoAP. To use provisioning, you need a vendor ID through a Whitelabel account with Exosite or by working with an existing Vendor that can provide a Model ID to use.

HTTP Provisioning / CoAP Provisioning

The Provision API requires a unique serial number. Typically this is a MAC address, serial number that is readable by software, or a cellular ESN/MEID.

When the device activates with the platform, store the provided CIK from the platform in non-volatile memory. The CIK is only provided once.

Have the device code check for activation at power-up or if receiving HTTP 40x error responses, even if it has a good CIK already (i.e., activated once). This is because the device may be re-enabled by the user or an application, which will generate a new CIK. It may also be deleted by the user and added by someone else, which is very typical for evaluation / demo kits. You can find a good device state flow chart diagram here.

Vendors shoulduse their vendor specific host for API calls .m2.exosite.com which will allow us to improve performance over-time as more connections are made.

In-Field Firmware Updates / Content(vendor accounts)

The Provisionin g API allows content to be downloaded to your device. This can be used for in-field updating of firmware, configuration files, media, etc.

Devices must be a part of a vendor client model and must be activated to access the content. Content is listed for the specific Client Model devices, each individual devices should make the API request to either list all content, get information on a specific content item, or download a specific content item. Content can be published for client models; each piece of content has a specific identifier, timestamp, type, and meta field. The timestamp and identifier can be used to check for downloading content.

Developers can create their own custom scheme for how devices know when to download new content. Versioning can be done by using an identifier name scheme like 'firmware_v1', 'firmware_v2', or by using the timestamps of the files to determine if it should be downloaded and applied.

The actual use of content on the device is up to developers, whether it is to update the firmware, applications, for configuration, or files like images for various media applications.

If performing in field firmware updates, be sure to follow best practices including checking checksums, verifying full downloads, having a back-up device bootloader, etc.

HTTP Provisioning / CoAP Provisioning

Plan for Scaling(vendor accounts)

If you have a Provisioning Vendor ID (any business solution account), be sure to use the specificvendor API address. The format is typically<vendorid>.m2.exosite.com. This can be found on your Portals solutionadmin home page (https://<vendorid>.exosite.com/admin/home) under Vendor API information. This is important if we need to work with you to off-load network traffic or customize the API handling for your devices.

Improve Troubleshooting for Users / Technicians / Developers

Debug Output / Status Indicators

Many devices that will be connected to Exosite do not have a screen or user interface. We recommend usingLEDs to provide some type of status and error conditions for the network connection and Exosite provisioning.

Examples:

Blink an LED once per second if no network connection, twice per second if can't connect to Exosite, keep on if connected and working.

Have a debug serial port that lets user know status conditions (this is more for developers)

Helpful HTTP Headers

For HTTP requests, add a "User-Agent" header. This enablesus to help you trouble-shoot, examine your network load, and handlecustom requests. Below is an example of theformat:

User-Agent://

Example User-Agent:acme_bg100/bg1xx_firmware/1.3

NOTE: If you are using an Exosite library or Activator code, we recommend using this for your code identifier.

Suggestions for DevelopmentKitVendors

Provide source code for client apps for kits and demonstrationdevices.

Give users a SDK / library for the Exosite commands for their own applicationdevelopment.

Provide command line options to program CIK manually

Provide good debug messages on responses from the Exosite platform (e.g. HTTP Responses)

The One Platform is a hosted server-based system that allow for developers to connect and manage products and applications using web service APIs. Devices become a virtual 'Client' in the One Platform, in a hierarchy of other clients representing devices, users, and account owners. This hierarchy can then be used to mimic the real-world use case of device and data ownership.

The platforms simple interface and Portals web dashboards makes it easy to build a connected solution application. The Platforms architecture and scripting interface make it powerful enough to manage fleets of product deployments.

What is the One Platform?

At a basic level, the One Platform is an application running on a server. It handles many concurrent requests from clients including devices talking to it's API, Web Portals, and other applications. It uses identifiers to authenticate connections and accept requests like read, write, edit, create, etc. The One Platform uses a couple of data bases, one to store the hierarchy of elements (clients, resources) and one to store actual data.

Clients Overview

Client Models - Deploying Many

Whitelabel / Vendor Accounts

Hierarchy

One Platform Scripting

One Platforms structure is made up of fundamental elements, the first of which isClients. Clients are entities in the OneP that have ownership and have resources. A client can be a parent or a child to another client, thus providing a strict control hierarchy of access. The most common scenario to envision is the main application adds users which add devices they own. When a user logs into the application, it would have stored the key (credential) for that users client in the hierarchy. The user only sees child clients (devices in this case) they own. Thus the application provides the linkage when the user logs in to the key for that users client in the hierarchy.

Data In/Out

One Platforms APIs are shell services that perform specific tasks. Some of these APIs are just for sending data to be stored into a data port for the device client. Other APIs actually are function calls, possibly creating resources for a device client, creating a child client, reading out a set of data, etc.

API and Libraries

Resources of a Client

Data, Rules, Scripts, Dispatches

Every client entity in One Platform can have resources, which include data ports, data rules, and dispatches. Each of these can be accessed thru APIs, to create, modify, write, and read. There is no theoretical limit of the number of resources a device has, it is really up to each application on how they are used.

Data Ports (Data Sources)

Data Ports are used to store data with time-stamps, as time-series based information. Data could be simple integer or float values for sensors or it could be string information as large formatted packets of data, firmware files, etc. The time-series history retention can be controlled by number of points, time period, or memory storage. This data is available on-demand for data rules and scripts to process or API function calls such as read. Data can also be combined to populate other data ports.

Data Rules: Scripts

Data Rules have two flavors. The first data rule flavor is script applications that have access to all of the clients resources to use for creating more advanced conditional rules or create algorithms to process data. These scripts are written in Lua language, have access to the clients other resources as variables and functions, and have the ability to call dispatches.

Data Rules: Events

The second data rule type is simple logical statements that can be applied to data ports over a number of points and/or time. If data port value is greater than x, y times, over time period n, then it is true, otherwise false. Logical data rules can be attached to multiple dispatches.

Dispatch

Dispatches are requests out from One Platform (an output). Most communication is done with the APIs as client requests and responses from OneP. Dispatches allow for the OneP to send information out, whether it is email, sms, xmpp, http, or even twitter. Dispatches are essentially ready to go messages that simply need to be triggered to send with a packet load. Triggers are data rule logic statements or script function calls.

We've listed some common knowledge about using HTTP and HTTPS. There are of course many articles regarding this topic available on the web, but we'll try to cover those that we see as common questions and issues from our users here. These hope to deal with common questions and mistakes we see when users are working with our API.

URL Encoding - Percent Encoding

When working with HTTP requests, it is important to think about URL encoding, especially when working with strings that are being packaged to form the HTTP request. I'd recommend reading up on Wikipedia about URL Encoding (also known as Percent Encoding).

An example, for a HTTP GET request to read data from a data source that has an alias of "test data". In this case, the alias has a space in it, a non-alphanumeric character. The One Platform does support any byte characters in the alias field.The GET request would look something like this, notice "test data" is encoded to "test%20data".

Proper Request

GET /api:v1/stack/alias?test%20data HTTP/1.1

Host: m2.exosite.com

Accept: application/x-www-form-urlencoded; charset=utf-8

X-Exosite-CIK: 27951d1a260b4b258fe......

Proper Request Response

HTTP/1.1 200 OK

Content-Length: 17

Date: Thu, 04 Apr 2013 14:11:28 GMT

Server: misultin/0.8.1-exosite

Connection: Close

test%20data=hello

If I did not do this, I would get an error response because the server is getting a bad URL request.

Improper Request

GET /api:v1/stack/alias?test data HTTP/1.1

Host: m2.exosite.com

Accept: application/x-www-form-urlencoded; charset=utf-8

X-Exosite-CIK: 27951d1a260b4b258fe......

Improper Request Response

HTTP/1.1 400 Bad Request

Content-Length: 24

Date: Thu, 04 Apr 2013 14:29:15 GMT

Server: misultin/0.8.1-exosite

Connection: Close

HTTP/1.1 400 Bad Request

Required Newline characters CRLF ( \r\n )

HTTP requests require newline characters after each line, for requests that include a body (POST) you must have a empty line between the headers and the body, and for GET requests to end with an empty line after the headers. This is so the server knows the headers are done and if it should wait for anything else before acting upon the request.

For systems and code bases that provide HTTP libraries or modules, this may not be important as the module does the work for you. For embedded systems that require you to create the HTTP packet as characters to send over a serial port for example, you will need to make sure to include the newline characters CRLF ("\r\n").

If you are getting "HTTP/1.1 400 Bad Request" messages, check each line you are sending ends in CRLF and that you have included the empty line after your headers.

An example, for a HTTP POST request to write data to a data source that has an alias of "data". The POST request would look something like these two examples which are identical, the first is just broken up line by line, notice the blank line between Content-Length header and the body (data=1).

Proper Request (line by line)

POST /api:v1/stack/alias HTTP/1.1\r\n

Host: m2.exosite.com\r\n

X-Exosite-CIK: 27951d1a260b4b258fe......\r\n

Content-Type: application/x-www-form-urlencoded; charset=utf-8\r\n

Content-Length: 17\r\n

\r\n

data=1

Proper Request (continuous characters)

POST /api:v1/stack/alias HTTP/1.1\r\nHost: m2.exosite.com\r\nX-Exosite-CIK: 27951d1a260b4b258fe......\r\nContent-Type: application/x-www-form-urlencoded; charset=utf-8\r\Content-Length: 17\r\n\r\ndata=1

To ensure continuity of service, all clients connecting to the One Platform and Murano (domain "m2.exosite.com" and all sub domains) must update their X.509 trusted certificate store to include the "DigiCert Global Root CA (November 10, 2031, 12:00:00 AM GMT)" certificate ( https://www.digicert.com/digicert-root-certificates.htm ) before March 6th, 2019. Clients that do not trust the specified root certificate will no longer be able to connect to the One Platform and Murano after May 6th, 2019.

Clients that do not trust the root certificate will experience service disruptions on the dates indicated in the table below:

March 6th UTC 2:00 am - 4:00 am

March 11th UTC 9:00 pm - 11:00 pm

March 25th - one day

March 27th - one day

April 8th -15th - one week

May 6th - non complying clients will no longer be able to connect on and after this date

A test domain https://digicert-test.m2.exosite.com is available that serves the new root certificate. Please use this domain to validate that your device and application clients can open a trusted connection with the One Platform and Murano. Clients should not use this domain except for validating trust of the new root certificate. All clients should use their assigned vendor domain. The test domain will be removed on May 6th.

For certain embedded device clients that can only store a single trusted root certificate, those must be updated to connect to the One Platformand Murano through their assigned vendor domain, and you will need to schedule a date with Exosite Support to have the assigned trusted root certificate updated prior to March 6th.

Please note:

If your devices are OS based (Linux/Android/Windows) that receive regular security updates, your OS trusted certificate store may already contain the DigiCert Global Root CA. Please verify that your OS trusts the specified root certificate.

If your devices are firmware based, you will need to deploy a firmware version that trusts the DigiCert Global Root CA.

If you have any questions or to schedule an early root certificate update for your assigned product vendor domain please contact our support team.

February 15, 2019

Exosite has provided free development kit and community IoT dashboard portals (what we called our 'Portals' application) for over 9 years. We've been happy to provide these applications and our older IoT platform called OnePlatform for all of these years to let people try out IoT and create some very cool applications, usually as the starting point for larger IoT projects.

Exosite will beendingnew sign-upson these community developer portal domains, including but not limited to:

portals.exosite.com

ti.exosite.com

renesas.exosite.com

microchip.exosite.com

atmel.exosite.com

Before the end of 2019, we plan to shut down these free portal domains and focus our efforts and users on our newer products. More details about this to come with information for those looking to evaluate our industrial IoT solutions.

Note: Thisdoes notaffect our paid whitelabel Portal / One Platform customers.

If you are looking for a commercially available Industrial IoT solution, please check out ExoSense.

For those looking for a consumer product solution, our ExoHome provides all of the tools and applications for a complete solution.

If we can help you in your IoT journey, please reach out to our support or sales teams for more information.

Custom Hostnames

What is a Custom Hostname in Murano?

Provided you have an Enterprise Business Tier, you can host your Murano Applicationat *.yourdomain.com with your Murano Businessaccount. With this you can fully customize your Solution to represent your internet connected Product.

You will need to have purchased your own domain name first, and you willneed to manage that domain through DNS or the tools that your provider gives you.

CUSTOM DOMAIN / HOSTNAME FAQ

Do I need SSL certificates?In order to support your custom Solution hostname you will need to provide your own certificate for us to install on Exosite's Murano platform (see below).

Cant you get a SSL certificate for my domain?We cant. The owner of the domain (*.yourdomain.com) needs to order the SSL certificate.

So I need to give you my private SSL certificate if I want SSL on my server?Yes. We require SSL on Exosite Murano custom Solutions.

Do you support Wildcard certificates?Yes. You may provide us with a certificate for a Wildcard Fully-Qualified-Domain-Name (FQDN).

SETTING UP A CUSTOM DOMAIN / HOSTNAME PROCESS

For EnterpriseBusiness Tierswho would like to use their own hostnameinstead of yourname.apps.exosite.io, the following steps are followed to set up the custom hostname. Please contact Exosite Sales or your Account Manager for more information about this option as it is only available for accounts at certain BusinessTiers.

The initial Solutionin Murano (exosite.io), e.g. *.apps.exosite.io, has to already have been created.

Submit a ticket to us (Exosite Support) using the subject 'Custom Hostname' with your BusinessID and SolutionID in the body so we are aware of which Solutionyou would like updated. Also be sure to include what you are planning to have it mapped to (your custom hostname) along with any contact information in case we need to call you directly. Your FQDNshould have at least two dots in it; for example, "iot.exosite.com" is a validcustom hostname, but "exosite.com/iot" is not.

Your company's IT team, or whoever manages your websites, will need to generate a CSR file ( Certificate Signing Request ).Here are the recommended fields when generating your CSR. Most CSR generation tools will walk you through what's needed:

Country Name (2 letter code): e.g. USState or Province Name (full name): e.g.MinnesotaLocality Name: e.g.MinneapolisOrganization Name: e.g.the name of your companyOrganizational Unit Name (optional): e.g. Information TechnologyCommon Name:(your custom domain) e.g. portal.yourdomain.com OR *.yourdomain.comEmail Address (optional): e.g. [email protected]

Your IT team will need to send the CSR to a certificate signing authority.

Your IT team then provides the SSL certificate and Private Key, in PEM format, from the certificate signing authority to Exosite through the channel negotiated with, via the ticket,Exosite Support.

Exosite adds this SSL certificate to our platform.

Exosite provides a DNS record for your IT team to add to your domain's DNS, along with instructions on making that change.

Exosite associates the new custom hostnamewith your Solution.

TROUBLESHOOTING

If you work with Exosite to set up a custom hostname, with all of the DNS configuration and Cert files that have to be set up, something can go wrong. Here are some things to look for, or use.

DNS Look-up

To verify that the DNS record is set up properly, you can use the tool called dig (Domain Information Groper). This tool will output information from DNS name servers to check that what you thought you set up is actually what was created.

This guide will teach you how to invite other collaborators to your business. Use this to invite your team and launch your Internet connected Product on Exosite.

After logging into your into Murano account, view the businesses owned by your accountby clicking 'My Businesses' menu item from the drop down on the top-right of your screen.

[email protected]

You will now see a page which displays all the businesses associated with your account. Select the business which you would like to share.

Examine the Business Name in the top-left area of the page to make sure you are editing the correct business.

Once you are sure you have have selected the right business, click on the 'TEAM' menu item, then click on the '+ NEW TEAM MEMBER' button to begin sharing your business. Enter the new member's email address and click 'CREATE' to send an invitation.

Congratulations! You have now shared your business with another user. Your new business member can now log in, access your business, and work with your to create your Products and Applications. NOTE: Make sure to be careful about who you give access to your business. Admins have the power to make changes to your business!

If you have any trouble inviting members to your business, feel free to contact for help.

Researchers recently discovered two new security vulnerabilities, known as Meltdown and Spectre, that affect most modern computing devices and systems. In this statement, Exosite shares the information we have about these vulnerabilities, the steps weve taken to protect our customers from them, as well as additional information and recommended actions for our customers to take to protect themselves.

Background

A design characteristic in modern processors introduced two vulnerabilities,Meltdown (CVE-2017-5754) andSpectre(CVE-2017-5753 and CVE-2017-5715), affecting CPUs from Intel, AMD, and ARM.

Meltdown primarily affects Intel CPUs and circumvents normal security boundaries, allowing malicious applications to harvest credentials or other sensitive information from a system's memory. Experts suggest that Meltdown has the highest probability of exploitation and could even be accomplished through simple means, such as JavaScript within a browser.

Spectre not only affects Intel processors, but also AMD and ARM processors. It can allow hackers to harvest sensitive information from applications. Experts indicate that this flaw is harder for hackers to exploit, but may also be more difficult for companies to fix.

Although there have been no reports of attackers exploiting either vulnerability, demo code has been released to demonstrate the methods that may be used to exploit Meltdown. In response, many companies will provide software and firmware updates to help mitigate vulnerabilities.

Exosites Response

In alignment with our Terms of Service, Exosite is working to ensure the protection of our customers confidential information, including any confidential information housed on our Murano platform.

Exosites Murano platform runs on Amazon Web Services (AWS), an ISO 27001 and ISO 27017 certified cloud services provider, and our core services leverage the Amazon EC2 service. AWS has indicated that their EC2 fleet is protected from all known threat vectors associated with both Meltdown and Spectre. See their security bulletin for additional information.

In addition to the patches Amazon has applied, Exosites security team is working to test and apply Meltdown patches from trusted operating-system vendors as they become available.

Recommended Customer Response

Because of the widespread nature of these vulnerabilities, Exosite recommends that our customers take appropriate action to protect their systems, including carefully monitoring the availability of updates provided by trusted device manufacturers and trusted operating-system vendors and applying these updates as applicable. This may include:

Applying available Windows updates (KB4056892). See the Microsoft Update Catalog for additional information.

Applying available browser updates.

Applying vendor-provided BIOS hardware updates.

Summary

Exosites security team has been watching this issue since it surfaced and we have been monitoring the status of AWSs response to ensure the confidentiality, integrity and availability of our Murano platform. As the situation progresses, we will make additional information available via our support site ; customers may also contact Exosite Support directly with questions or concerns.

Quoted from ARMs website, The ARM mbed Device Connector service lets you connect Internet of Things (IoT) devices to the cloud without having to build infrastructure, while providing security, simplicity and capacity required by developers to prove IoT applications at scale. For more information, please refer to https://connector.mbed.com/.

Murano mbed service provides a way to connect your mbed connector accounts to Murano applications. It enables Murano application developers to access device data and device status within Murano via the Murano mbed service.

With Murano mbed service, Murano application developers can connect an mbed connector to Murano, and have their mbed devices mirrored in Muranos Advanced Device Connectivity (ADC). This will allow mbed device data and events such as device registration/unregistration to be visible within Murano. With this association, you can use Muranos feature-rich services to build your IoT solutions with mbed devices.

Requirements

Have an mbed account

Have access to Murano mbed service. (Hint: only a professional-above tier business is able to purchase mbed service through the Exchange UI)

Getting Started

There are several steps required for initializing this service.

Step 1: Create an application

Create an application in your Murano business. Instructions for creating an application can be found at http://docs.exosite.com/reference/ui/create-application/.

Step 2: Create and configure a product

Create a product in the same Murano business. Instructions for creating a product can be found at http://docs.exosite.com/reference/ui/create-product/.

Configure your product

Choose CIK (Client Identification Key) as the authentication method for Https Data Api

Configure Device Identity Format to match the format of an endpoint name from mBed Connector (e.g. prefix =, type = Opaque, required length = 36)

http://docs.exosite.com/reference/services/device2

Create Resource

Navigate to the Resources tab within the product.

Click +New Resource button and fill in Alias as defined in mbed Resource Path but replace / with _; for example, resource path: /Test/0 resource alias: _Test_0

Select String as Data format, since the data are reported as String from mbed

Please note that the following image is only shown when there is a device connected to the mbed account.

Step 3 Subscribe/Add Mbed service in Exchange for your application

After the application and product have been created. You can now subscribe to Murano mbed service. For more information on how Murano Exchange works, please refer to http://docs.exosite.com/reference/ui/exchange-guide/.

Step 4 Configure your mbed service.

In service config tab, fill in API Key, Product ID, endpoint type. Make sure you have your working API Key

Step 4.1 Go to the mbed service under service config page of your own solution

Step 4.1.1 Go to your own application-type solution

Step 4.1.2 Click SERVICES tab and then click Mbed at left services navigator

Step 4.2 Fill in (1)Product ID (2)API key (3)Endpoint Type as parameters for the mbed service (Note: the match-all star sign (*) doesnt work for endpoint type, must input a specific type like in Step 4.2.3)

Step 4.2.1 To fill the value for parameter(1)Product ID, please refer to the following screenshots:

Step 4.2.2 To fill the value for parameter(2)API key, please refer to the following screenshot:

Step 4.2.3 To fill the value for parameter(3)Endpoint Type, please refer to the following screenshot:

Step 4.3 Click APPLY button and you should see Service config updated successfully message

Step 5 Verify

Step 5-A. Check if new device is created

Go to Device page, and you will see the device, which has been successfully created and provisioned.

Step 5-B. Check if data is reporting

Click the device, and you will see the resource value, which has been updated

Step 5-C. Check if mbed devices are listed by endpoint/route verification

Step 5-C-1 - Associate application with product

1 - Entry the application-type solution page

2 - Click SERVICES tab

3 - Click Products at left services navigator

4 - Check the checkbox next to the applicable product

5 - Type Mbed20170911(for example) as script alias next to the EDIT SCRIPT

Note: Mbed on it's own cannot be used as the Lua Script Alias

6 - Click Apply button

7 - After you see the Products updated successfully message on Snackbar, you have associated application with product successfully

Step 5-C-2 - Check if mbed devices are listed by calling device2.listIdentities() in endpoint

1 - Click ROUTES tab under application page

2 - Click + NEW ENDPOINT

3 - At the New Route pop-up, type mbed/devices(for example) in path field, and click CREATE button

4 - Entry the new created endpoint and write down the Lua code as below:

return Mbed20170911.listIdentities()

Note: To successfully use device2 public API, the alias device2 must be substituted with script alias created in Step 1.5(which is Mbed20170911 as example here); further information about device2 APIs, please refer to:

5 - Click the link for AUTO-GENERATED DOCS

6 - Click the Try for mbed/devices route

7 - Should see all the mbed devices

Aeris is a US based MVNO that enables IoT devices to connect to the internet through the use of cellular networks.

This guide will walk you through activating your Aeris SIM card and connecting to Exosite with a cellular gateway.

Prerequisites

You will need the following pieces of hardware to complete this walkthrough:

An Aeris SIM card - can be purchased from the Aeris Store

A gateway that supports AT&T SIM cards, such as a Multitech Conduit

Setup

The outline of this guide will be as follows:

Provision and activate SIM card through Aeris' dashboard

Add SIM to compatible Multitech Conduit

Enable the Multitech Conduit to use the correct APN

Run a short program that enables the modem, waits for an input change, and writes the data to Exosite

Provision and Activate SIM Card Through Aeris

To provision your SIM card, you will need to go to the Aeris Dashboard.

This is the dashboard page that shows account overview information. We want to activate a SIM card, so select the Devicestab from this page.

here

You can see the devices that are already registered on the devices page. To Add another device, click the SIM Inventorybutton on the top toolbar.

This will bring you to the SIM inventory page that shows the sims that are associated with your account.

By default, 2G SIM cards are shown. Change the dropdown filter to LTE to see LTE SIM cards.

This should show SIMS registered with your account. To add a new SIM, find it and look at the number of the back.

Select the SIM you want to provision, then select a plan for the SIM card.

After the SIM has been added, you will be taken to the SIM page that shows information about the SIM card.

After adding the SIM and going back to the dashboard, we can see there are now two SIMs.

This means the SIM card is ready to be used!

Sending Data with the Multitech Conduit

The next step of this walkthrough is to use the SIM we just registered to send data to Exosite. We will do this very simply to focus on getting something working as quickly as possible.

The hardware used for this is a Multitech Conduit MTCDT-H5-210L with a GPIO mCard and a GPIO cable. The Multitech Conduit uses mLinux, so the setup instructions will be different if you are not using a Multitech Conduit.

Log in to the conduit - connect the USB serial cable and connect to the newly registered serial port at a baud rate of 115200. You should be presented with a login prompt, enter the login information matching your hardware.

After entering, you should have access to a shell where you can run commands.

Set the Aeris APN to "iot.aer.net" (info available ) with the following command:

# mlinux-set-apn iot.aer.net

After that, create the following file on the device:

#!/bin/bash

# MODIFY TO YOUR SETTINGSPID=""CIK=""# END MODIFICATION

if [ -z $PID ] || [ -z "$CIK" ]; then echo 'PID or CIK not set... exiting...' exit 1fi;

echo 'initializing cellular modem...'

pppd call gsm

trap ctrl_c INT

function ctrl_c() { echo 'shutting down cellular modem' killall pppd

exit 1}

while ! ifconfig ppp0;do ps -A | grep ppp sleep 0.5done;

echo 'Cell connection established'echo 'Waiting until IP address is granted...'sleep 0.1until ifconfig ppp0 | grep 'inet addr:'; do :; doneecho 'Waiting for input change...'

LAST_BUTTON=0COUNT=0while :do BUTTON=$(mts-io-sysfs show ap2/din0) if [[ $BUTTON -eq 1 ]] && [[ $BUTTON -ne $LAST_BUTTON ]] ; then COUNT=$((COUNT+1)) echo 'The count is: '$COUNT curl --request POST \ --url https://$PID.m2.exosite.io/onep:v1/stack/alias \ --header 'content-type: application/x-www-form-urlencoded' \ --header 'x-exosite-cik: '$CIK \

--data "count=$COUNT" fi LAST_BUTTON=$BUTTON sleep 0.05done;

The script above has two lines that need to be edited to match your Exosite product (the PID and CIK).

The script will turn the cellular modem on, wait for a connection to be established, wait for an IP to be registered, and then send an event to Exosite every time the din0 pin has changed.

The following shows the output from the script after running, waiting, and then pressing the button two times.

Linux-class Gateways

The Exosite Gateway Engine is used to connect up pretty much any Linux-capable gateway with python support. Since the networking, development, and application run-time environments on these devices are all similar, lighting up a new gateway that is not shown below typically takes just a couple of hours.

Here are some gateways that are being used with Murano:

System:

Updated On:

Multitech Conduit

Q3 2017

Janus 400AP

Q3 2017

BeagleBone

Q2 2017

Option Cloudgate

Q2 2017

Raspberry Pi

Q2 2017

WIT Gateway

Q3 2017

Advantech Gateways

Q3 2017

Embedded Devices

Embedded devices have varied networking support, development environments, and application run-time environments. Although some platforms are supported through our Exosite Ready ANSII C SDK, most of the examples below implement a variety of ports in the native development environments from the silicon manufacturer.

Here are some embedded devices that are being used with Murano:

System:

Updated On:

Sparkfun ESP8266 WiFi ThingBoard

Q3 2017

Atmel AT88CKECC-AWS-XSTKdev kit

Q3 2017

TI CC3200-LAUNCHXL Wi-Fi Launchpad

Q2 2017

Realtek WiFi-based systems

Q2 2017

Cypress WiFi-based systems

Q2 2017

Mediatek WiFi-based systems

Q3 2017

Libraries and Frameworks

Gateway Engine - A connectivity framework for Linux-class gateways with python support. Used commonly in industrial gateways to connect different industrial protocols and sensors to Exosite.

Arduino Library - A library that can be added into the Arduino tool chain for easy development with Murano. Used commonly by students, hobbyists, and day-job engineers to prototype connected concepts.

Python Library - Example connectivity simulator written in python. Commonly used to get some data flowing quickly to Exosite when you don't have hardware around.

Exosite Ready ANSII C SDK - Used to collaborate with certain hardware partners to deploy a production read, secure, OTA-capable, development environment using the GCC toolchain.

The purpose of this article is to list hardware platforms that either we or our customers have not been able to connect to Murano.

We are confident that if you can open a socket andcomplete a TLS handshake with your Product endpoint then your hardware can work with Murano. Problems don't happen often, but when they do, we want to publish our findings!

Unverified Hardware:

Arduino MKR1000 (We suspect that there is an issue with the client certificate this device presents to Murano. We haven't yet confirmed this issue.)

Introduction

We have noticed for returning users who have created a business profile prior to the Murano platform launch, that they run into an apparent loop within the business interface of Murano. When this manifests, it looks like you can log into Murano, but are then presented with a screen notifying you to request access to Murano. This article will teach you how to move past this obstacle and get up and running on Murano.

Don't worry, there is nothing wrong with your account, and you shouldn't need to request access to Murano any longer. You have access to Murano already, it is just initially hidden from you. Follow the steps below, and you should be creating a new product and solution in a few minutes.

Step 1: Log in with your account at www.exosite.io.

There shouldn't be any need to sign-up again. Feel free to log in and and prepare for Step 2.

Step 2: Click on the left-hand navigation stack.

In the top-left corner of your screen you should find a small button that looks like three stacked plates. This is the navigation stack. Click on it to access the Murano interface menu.

[email protected]

Step 3: Click on the 'Switch Business' link at the bottom of the navigation pane.

You should find that your screen has darkened, and a new pane has appeared on your screen. In this new pane look for the 'SWITCH BUSINESS' link located on the bottom of the pane and click it.

Step 4: Create a new Murano enabled business.

You should now be taken to a page, where you can view the businesses of which you are a member. From here you can create a new Murano enabled business, and begin using the platform. Click on the 'Create Business' button to start naming your new business profile. Feel free to name you business anything you would like, there are no uniqueness restrictions. We do however recommend a naming convention, or something that while help you sort your Portals-basedbusinesses from your Murano enabled ones. We often use Murano - <Name> as you will see in the screenshot below:

Conclusion

You should be switched over to Murano enabled business and interacting with Exosite's latest technology.If you find that you have additional trouble or have questions, feel free to contact us at .

We are aware of the hurdle that this presents, and we will be making improvements to the user interface. Stay tuned for more updates!

contact us

Created for the Internet of Things (IoT), the SimpleLinkCC3200Internet-on-a-chipsolution is a wireless MCU that integrates a high-performance ARMCortex-M4 MCU allowing customers to develop an entire application with a single IC. With on-chip Wi-Fi, Internet and robust security protocols, no prior Wi-Fi experience is needed for faster development. The Texas InstrumentsCC3200-LAUNCHXLWi-Fi Connected Launchpad is a development kit for the CC3200 wireless microcontroller.

Right now Exosite does not have an example embedded application for this hardware platform that works with our Murano platform. You can look forward to us remedying this later this year.

In the meantime we know that the device is fully capable of connecting to Exosite Murano through our device API -- Feel free to register an account and connect it to Exosite for free!

Downloads and Links

Purchase the Kit

Pricing / Quotes Contact

Murano Device API documentation

How Data moves in Murano

TI CC3200LaunchPad Overview

TI Engineer 2 Engineer (E2E) Forums

TI Software and Tools

TI CC32xx/31xx Wiki Page

Debug USB Port

The debug USB port for the Connected LaunchPad provides a useful console for getting notified of what the device is doing and for accessing features of the application. Use a Terminal program like TeraTerm or Putty to use the virtual serial port over the USB connection to your computer from the device.

To use the Virtual COM port, see the CC3200 LaunchPad's getting started guide for instructions for installing the needed Windows drivers. Once installed you can connect a terminal application to the COM port running at 115200 baud, 8-N-1.

Computer - Device Manager - COM Port

Support

If you run into issues connecting to the cloud, or have other questions, use the following resources:

Texas Instruments Engineer to Engineer (E2E) Forums - For all device questions

Exosite Forums - Forquestions you need to ask of Exosite

docs.exosite.com - Documentation on all things Exosite software

If you'd like to learn more about Exosite and what we can offer product companies to deploy connected devices and device/data cloud applications, please .

Murano is Exosites second-generation IoT Platform, forged through insights from One Platform/Portals users, and offers enhanced usability and capabilities intended to further accelerate an IoT journey. The Murano platform is purpose-built to give developers the tools and flexibility to create a custom IoT solution for any organization, and it strips away some of the custom limiting attributes of One Platform/Portals.

Application Asset Hosting

The Murano platform allows for hosting and deploying static front-end applications.

One Platform/Portals only allows branding of a pre-defined UI and requires a separate hosted application with a front and back end.

Application API

Murano offers a fully custom Application API per solution with concepts of user roles and permissions.

One Platform/Portals provides an application API limited to the scope of the Portals hierarchy and user roles/ownership concepts. It is not customizable. To create a custom API, one must go completely custom with an outside hosted backend/frontend using the One Platform RPC.

Device Ownership/Data Access Permissions

Murano supports a completely custom provisioning scenario that can be separated from the application device access concepts. Both consumer and industrial scenarios are supported within Murano.

One Platform/Portals, by contrast, only supports a rigid hierarchy for device ownership and provisioning, which is only ideal for some applications.

Time Series Data Store

Murano has support for Millisecond resolution using True Time Series Database with Query Support.

One Platform/Portals, has 1 second resolution for its time data store within the platform.

Key-Value Data Store

Murano utilizes redis for its Key-Value data store

One Platform/Portals does not support the Key-Value data store concept.

Third-Party and Service Integration

Murano offers services and integrations within the platform that are implemented the same way and can be efficiently scaled. Murano will also be releasing IoT Exchange in mid 2017 that will allow for the immediate inclusion of additional premium integrations and services into your project.

One Platform/Portals does not offer any out-of-the-box services or integrations and requires custom service development and hosting.

Scripting

Murano uses scripting to route data to services and for handling all events in the platform. This scripting method is extremely efficient and has access to all service functionality directly. Absolute customization of the solution is allowed through this scripting method.

One Platform/Portals handles real-time data stream processing and some hierarchal platform management functionality. This is limited in scope to only certain thresholds of the platform and how they are triggered to run.

Have you created a Product with more than 50 devices under it?If you use the UI to verify that devices have been created, you may notice some strange behavior once you pass this threshold.

If you take a look at our Device Service API you may notice that the Device.list() function returns 50 devices by default. Currently, ourUI emulates this in order to displaythe devices under a Product, thus leaving some devices without a place in the interface. Rest assured, if you are using a valid process to create your devices, they are in fact being created and do exist in the system for use, this is a bug that affects only the UI. To verify that all of your devices have been created, use the API directly and specify a limit beyond the default 50.

Of course if you have any questions or run into any trouble, do not hesitate to contact Exosite Support at: https://support.exosite.com/hc/en-us/requests/new

Canceling Developer Accounts

If you have a user account on portals.exosite.com or another domain <subdomain>.exosite.com you can go to your account page (user name drop-down menu in upper right corner) and cancel your account.

[email protected] https://portals.exosite.com/account/profile

or

https://<subdomain>.exosite.com/account/profile

Within the account page you will find that Exosite will ask for confirmation before canceling your account. Confirmation includes a warning reminding you that all data and personal settings will be lost. Type in your password and you are done.

Canceling BusinessAccounts

If you have purchased a Portalsor One Platform API Solutionand would like to cancel your subscription, please contact us by emailingus at [email protected] submitting a ticket. Please provide your subdomain URL, Business ID, and your contact information within your message. This email/ticketmust be made using the email address of the originalpurchaser or current business owner.

After opening a ticket with Support, you can remove your solutions from your account. From the "Solutions" tabyou will see a list of the solutions owned by your business. There is a dropdown menuon the far right that looks like three vertical dots,there you will find the button "Delete". Clicking on this button, and confirming, will forever removeyour solution from the system.The screenshot below should help you delete any solution under your business.

Note*: Only the solutions that appear in your 'solutions' tab while logged into your business, can be managed by you. To view this list, login into your Business Account and select the 'solutions' tab.

If you have trouble finding your Business ID, remember you can find under "Account" >> "Profile". The screenshot below should help you pin-point your Business ID location.

If you have any questions, feel free to get a hold of us:

Do you have a script that is returning a "500: Lua Quantum Limit Exceeded" error? This is because of an instruction limit that is in place to prevent runaway Lua scripts. Every operation you do in a script will use one or many instructions, including loading modules. If your code is not efficient, or you load too many modules, it can cause this error to present itself and the script to fail. To avoid seeing this issue, we have a few mitigation suggestions:

Only load the modules you really need to use

Ensure that your code is as efficient as possible

If possible, break up complex operations into new handlers

Limit the number of queries to services

Consider pagination or make multiple queries

Of course if you have any questions or continue to run into trouble, do not hesitate to contact Exosite Support at: https://support.exosite.com/hc/en-us/requests/new

Before our January 16th Murano release, a call to a service that returned an array with one element would convert to JSON as an array (e.g., '{"measurements": [44]}'), whereas an empty array would convert to JSON as an object (e.g., '{"measurements": {}}'). Additionally, a result that contained a null value would be removed from JSON entirely, but will now be preserved. This may affect your solution if it makes calls to services like Tsdb that return lists of items. Here are some examples:

Now

After JSON conversion improvement

result = Service.method1()

return result

-- outputs {"measurements": {}}

result = Service.method1()

return result

-- outputs {"measurements": []}

result = Service.method2()

return result

-- outputs {}

result = Service.method2()

return result

-- outputs {"error": null}

Devices that have been created to connect with Exosite need to 'activate' to exchange a key so they can communicate with Exosite's platform in a secure way. This activation function also sets up a path of ownership for the device.

(Note: This does not apply to generic devices, which must have their CIK copied manually into their code)

When devices are not sending data, there could be one of several issues, including not properly activating, network issues, actual device issues, or unfortunately user error. This can cause headaches and we hope we can provide some help here, although we recommend using documentation and support from the provider of the device or reference software.

For specific device connection issues, we recommend looking over user guides and device information provided by the Product OEM, Development Kit provider, or if using open source code, where that code is documented.

This will cover the generic overview of device activation issues.

For developers, check out our provisioning guide

Most common problems:

Trying to activate a device that you haven't added to your account. Make sure to use the 'Add Device' wizard in portals and select your device Client Model from the available device type menu.

Entering wrong unique number / serial number / MAC address / MEID - Double check your number when entering it.

Adding a device still owned (claimed) by someone else - Contact that person if you got it from someone else.

Network issues - Verify the device is has a good internet connection to the outside world.

Development Systems / Kits / Reference Code

If you add your device to your portal but you never see data in the dashboard, check out these items in addition to checking the device's documentation and support methods:

Check that the device you added is theuniqueidentifierof your device. If not, it will not work, as you have 'claimed' a different device. It's good todouble check this. If you have added the wrong unique identifier, delete the device on the 'Devices' page byclicking on your device, and use the 'delete' function on the pop-up window)

Check if the device ever Activated. Go to the 'Devices' page by clicking the 'Devices' link on the left hand side of the window. Here you should see a table of your devices, click on the one in question. This will open a pop-up window showing information about the device. The status should say 'Activated'.

'Not Activated' - Then the device has yet to reach our platform to activate, which it should try to do when connected properly to a network that can reach our servers on the public internet. There is either a device problem or a network issue.

'Expired' - This means that the device did not activate with-in 24 hours after you added it. You canre-enable the deviceusing that pop-up window and using the Re-Enable function. This will put the status back to 'Not Activated' and you'll need to trouble-shoot why it is not activating.

If your device hasactivated, then you have verified it has connected to the Exosite servers at least once correctly and it's rare it would not continue to work. If you still are not seeing data, check that your internet connection is still ok. If the device for some reason did not store it's CIK properly when activating (power pulled at wrong time), you can 'Re-Enable' your device and let the device re-activate. Follow the previous step for when a device has Expired.

If the device hasnot activated, use available debug methods for the device's code to determine if there is a network or code issue. This will tell you if you have a local IP address. See below for the different debug console states.Most issues are related to the device not obtaining an IP address on your local network. This may require manual intervention for your local network.

Does the device only use Static orDHCPIP Addresses and what is your network set up for.

Some networks are configured to not assign IP addresses tounknown devices, check your router settings / IT administrators

If theMAC address is badfor some reason (next step), the local network may not like what is being reported and not assign an IP address

If you are in an office network,talk with your IT administrator, they may have some suggestions.

Check that the device has it's unique identifier numberprogrammed correctly.

OEM Products

If you have received a product or device from a OEM that uses Exosite, we recommend contacting that OEM or using the available support methods they provide regarding device activation issues and problems adding devices to the web portal.

Update: All of Exosite's APIs support some form of push or pseudo-push functionality. See CoAP Observe, HTTP Long-Polling, or RPC Wait. The method in this article still works, but the new API methods have fewer requirements.

The standard method for receiving data from the Exosite Platform is to simply poll the platform for new data. But, maybe you need faster updates or maybe you're on a mobile connection with a limited data allocation. What you need is push!Instead of asking the platform if it has any new data every few minutes or seconds the push method allows you to simply let the platform take any updates it gets and push them directly to your device as soon as it receives them.There are some requirements that your device will need to have for push to work. Mainly you'll need to have a publicly addressable IP address or other URL to tell the platform to push to. If your device will be behind a NAT router or other firewall, you may be able to use UPnP to request an open port. Second, your device will need to have some form of server that can receive HTTP POST requests.To accomplish the push we're going to use the HTTP dispatch feature of Lua scripting on the platform. Paste the following lua script into the scripting interface in portals and modify the variables in the "Configure These Variables" section.

-- This script simply waits until a new value gets written to a

-- datasource, then pushes that value to the specified url as

-- a URL encoded (ish) string of alias and value.

--------------- Configure These Variables ---------------------

local datasource_alias = 'led'

local url = 'http://198.46.157.16:13579'

---------------------------------------------------------------

local datasource = alias[datasource_alias]

while true do

local new_timestamp = datasource.wait()

local new_value = datasource[new_timestamp]

local body = string.format('%s=%s', datasource_alias, new_value)

debug(string.format('Sending Message: %s', body, date()))

dispatch.http(url,

"post",

body,

"application/x-www-form-urlencoded"

)

end

Note that this is NOT production-ready code and is for demonstration purposes only. If you plan to use this method with your product, you should add real urlencoding and some error checking.

You may want to first read this article on the data format in Exosite's platform.

Exosite's Data Format

When sending data to Exosite, you will need to determine which dataport or dataports to write to. Dataports are resources under a client object that hold time-series data. Essentially as you write to them, the value is held with a unix time-stamp so that you can go back and get the values over a time period. Only one value may exist at a specific time stamp. Any attempts to write a second value at the same time-stamp will fail.

There are two functionsto get data into Exosite. A 'write' and a 'record' function. The write method allows the platform to time-stamp the data when received with what the server's current time (now). The record method allows the sender to provide a timestamp along with the value and this is what is used in the dataport storage.

Choose an API

Some of Exosite's APIs only support write, some support both write and record. For devices, Exosite recommends using one of the following APIs:

HTTP Data - HTTP REST-like APIs supporting write and multiple write.

CoAP - CoAP based APIs that support write and multiple write.

RPC - There is a JSON RPC (HTTP transport) and a COBR RPC (CoAP Transport) that support both write and record functions.

What does a 'write' actually do?

The dataports are like global variables that devices and applications can write to with the proper authentication / access rights. When a device writes to a dataport, generally the API looks something like temperature=32.1, where 'temperature' is the alias of the dataport and 32.1 is the value. The 'alias' is essentially the global variable name, instead of using the resource identifier (RID) which is a 40 character hash value.

In this case, 32.1 would be stored with a timestamp inside of the platform. If any application or the device did a read at that specific timestamp, they would get that value.

Sending multiple dataports at a time

The APIs generally all support writing to multiple dataports with one call and take a format like temperature=32.1&humidity=45.

Sending multiple values to a dataport

For APIs that include the 'record' function, you can send multiple values with their unique timestamps. For example, the JSON RPC record function allows you to send an array of arrays like [[timestamp1:value1],[timestamp2:value2]].

Sending formatted data

The string type dataport can take a formatted string (JSON, XML, CSV, etc). A device could send a JSON packet in this way. That entire string is stored at a timestamp of course and is up to the application that is interacting / processing the data to decode it properly.

You could send a string like '{"temperature":32.1,{"lat":49.3233,"long":-49.090},"humidity":45}' for example. This would be stored complete and would need to be parsed by the application.

Example Use Cases

A device needs to send 5 pieces of information, some of which may be raw sensor data, some is more for information (device status, error messages).

Let's cover the 5 pieces of information this device has to send first. Data is held in the One Platform as 'Dataports', also referred to as Data Sources (this is the nomenclature Exosite Portals uses). Each of these dataports is time-series data, so in the One Platform, they store new values with a time-stamp when written to. If using a API that allows providing a timestamp, the platform will use provided time, otherwise it will use the server's timestamp when data is received. (Note: All data is stored with Unix Time Stamp, UTC)

Send each piece of data separately to it's own data port.

This approach will write to each dataport. Note, all of the Exosite API's allow for multiple dataports to be written with one request. If I were using the HTTP Data Interface API, it would look something like this:

POST /api:v1/stack/alias HTTP/1.1

Host: m2.exosite.com

Content-Type: application/x-www-form-urlencoded; charset=utf-8

X-Exosite-CIK: fff51d1a260b4b258fefffd9a9313c433e419fff

data1=34&data2=490&data3=ok&data4=test&data5=1

Send all of the data as a formatted packet to one data port and parse the data using a script.

This approach will write all of the data to one dataportasa string in some type of formatted data (CSV, JSON, etc). If I were still using the HTTP Data Interface API, it would look something like this below. Let's assume the data packet I want to send is JSON formatted data and is the same as approach number 1 above. The JSON packet would look like this and we would send it as a string to a data port called 'datapacket'. {"data1":34,"data2"=490,"data3"="ok","data4"="test","data5"=1}

POST /api:v1/stack/alias HTTP/1.1

Host: m2.exosite.com

Content-Type: application/x-www-form-urlencoded; charset=utf-8

X-Exosite-CIK: fff51d1a260b4b258fefffd9a9313c433e419fff

datapacket=%7B%22data1%22%3A34%2C%22data2%22%3D490%2C%22data3%22%3D%22ok%22%2C%22data4%22%3D%22test%22%2C%22data5%22%3D1%7D

Note that the body is URL encoded, that's why all of the % signs are showing up.

You may ask "Why would I do this?". Well, in doing this you now have one dataport called 'datapacket' that all data is sent to. Since it is formatted data, you may not send all of the data every time, you may just send one new piece of information (data1) or all of them. On the One Platform side of things, it has the rawpacket dataport receiving this data. You can write a script that simply waits for new values to 'rawpacket' and then parses it / processes it. This gives you a chance to convert the data before it is written to individual dataports. You could do this same thing with approach #1 above, but you would have a script for each dataport and you would have a 'raw' and 'processes' dataport for each.

Here may be what the One Platform script would look like to parse the data out of the formatted JSON string and put into individual dataports:

local packet = alias['rawpacket']

local temp = alias['temperature']

local sig = alias['signal']

local status = alias['status']

local debug = alias['debug']

local button = alias['buttonstatus']

local converttemp(tempC)

-- conversion code, perhaps convert raw analog to degrees C or F

end

local getusermessage(status)

-- use status to provide a friendly message to the user on the web portal

-- convert to a string to return

end

while true do

local ts1 = packet.wait()

local rawdata = json.decode(packet[ts1]) -- my data is in JSON format, decode it into lua table

if data then

if data.data1 then

temp.value = converttemp(data.data1)

end

if data.data2 then

sig.value = data.data2

end

if data.data3 then

status.value = getusermessage(data.data3)

end

if data.data4 then

debug.value = data.data4

end

if data.data5 then

button.value = data.data5

end

end

end

The reason you are likely seeing the "Execute JavaScript" button is because you are viewing apublic dashboard and there is a security risk since the creator of the dashboard custom widgetcould write javascript that could be potentially malicious. We restrict this to ensure Portals is not used to take advantage of any cross-site-scripting (http://en.wikipedia.org/wiki/Cross-site_scripting) and related games that can be played with javascript.

To remove the 'Execuite Javascript' message when viewing custom widgets, you must either be:

Logged in as the owner of the Portal that created the custom widget

Logged in and your user account profile has agreed to the accepts all javascript option. This can be set in your user profile (e.g. https://portals.exosite.com/account/profile ) or when you see an Execute JavaScript button, there is a second option to allow global javascript on any dashboard view.

(Recommended) Have promoted the custom widget to a 'domain widget' status through the subdomain administrator's /admin/domainwidgets page.

Domain Widgets

If you are using portals.exosite.com (or another evaluation site) instead of your own Portals Domain Solution, you only have option a) or b) available to you. Public dashboards will alwaysshow this 'Execute JavaScript' message to protect against malicious code that could be created.

Exosite's One Platform uses Client Interface Keys (CIKs) as authentication for all devices, users and other types of access to the cloud data platform.

CIK for Devices

If you are using Exosite Portals (portals.exosite.com) or asubdomainon Exosite Portals, you can typically find the CIK for a device you are using by logging in, and going to https://portals.exosite.com/manage/devices and clicking on your device. This will open the Device Information pop-up window which will show the CIK for your device.

Note if you are part of a subdomain, your URL will look something like: https://<company>.exosite.com/manage/devices

http://exosite.com/products/onep/documentation/device-interaction

Why can't I find my device's CIK?

If the Device Information popup does not show your CIK, it may mean that your device is part of a registered serial number pool for a device model. In this case, your device has to "activate" () with the One Platform for a CIK to be assigned.

CIK forPortals

You can find your Portal's CIK by going to /account/portals, or by selecting Account underneath your username in the upper right-hand corner of the page and choosing "Portals" on the sidebar menu.

TheCIK is located underneath the name of the portal next to the word "Key".

Yes:There are a few ways of exporting data:

Use the ExositeAPI

You can use our API to pull data out, we'd recommend the JSON RPC, which has a 'read' function with multiple options.

JSON RPC API

Here is an example python script that will pull data out and store within a CSV file:

Archive Data Utility.

Command Line Tool (Exoline)

The Exoline command line tool is a python application that uses Exosite's APIs to give users a quick way to access Exosite's platform. It provides commands to read and write data, check on scripts, look at the hierarchy tree of clients, make a copy of a client (device) and most importantly export data to a csv file. Information including installation steps can be found here: https://github.com/dweaver/exoline

An example of dumping multiple dataports to a csv file:

$ time ./exo.py read 2ca4f441538c1f2cc8bfaaaaaaaaaaaaaaaaaaaa gas temperature humidity event --start=5/1/2013 --end=8/1/2013 --chunkhours=24 > alldata.csv

real 1m58.377s

user 0m10.981s

sys 0m0.506s

$ wc -l alldata.csv

316705 alldata.csv

Here is an example of how to export all dataports for a given client CIK with a configurable date range and limit (max number of data points given per dataport):

#!/bin/bash# Usage export.sh <cik> > data.csv# Requires jq

CIK="$1"TYPE=dataportLIMIT=100000START=10/1/2013END=nowHEADER=nameTIMEFORMAT=iso8601

RIDS=$(exo listing $1 --type=$TYPE --pretty | jq -r '.[][]' | tr '\n' ' ')

exo read $CIK $RIDS --start=$START --end=$END --limit=$LIMIT --header=$HEADER --timeformat=$TIMEFORMAT

Download a CSV fromPortals

Note: This approach has limits on the number of data points that can be pulled and the time period you can select.

1. Go to your accounts data source manage page (e.g. https://portals.exosite.com/manage/data )

2. Click on the data source you are interested in to bring up the data source pop-up window.

3. On the right-hand side, there is a box called "Data Log". Next to that heading is a link called 'Export Data'.

Amazon S3

4. Click the Export Data link, which will open a box showing your data source selected (you can select others if you wish) and some calendar buttons to select a time period.

5. Hit 'Continue' button and the next window will provide you with a link (it actually says 'this link') and if you click that it will start to download a .csv file.

Note: There is a restriction on how much data for each data source (30 days) at a time.

Custom Domain Widgets

For Subdomain vendors that would like to provide options for end users to export data, the Widget API has a 'read' function that can pull data and is not limited to any number of data points. The custom widget would need to be written to provide the user a way to select the time period andprovide the userstatus, as it could take time to generate.

Custom Widget API Document

Example Line Graph that uses the widget 'read' function to graphmany data points

Other Options

We have other functionality to do a push archive to . Contact us for more information.

Overview

A dashboard is a one-page web page that has widgets containing different information, typically from the Exosite One Platform. A widget could be a list of data sources and values, a graph showing three data sources, or a simple text dialog box that provides information about the specific dashboard. A dashboard is tied to a portal account and all devices, events, and data associated with that portal areavailable for visualization in the dashboard.

A portal may have multiple dashboards depending on the account level. One dashboard is always set as thehomepage, which is the landing page afterlogging in. Dashboards can be shared with other Exosite account users depending on the account level and all dashboards are available to be shared with a public URL.

User Roles in Portals

Managing Dashboards

To view all dashboards for a portal, click on the "Dashboards" link in the navigation menu on the left-hand side of the screen.

User Roles in Portals

The management area for dashboards will show a list of the dashboards for the portal and a Add Dashboard button to add new dashboards. Each Dashboard has a name, description, a given URL, and a Configure button to edit the dashboards configuration.

Adding a Dashboard

On the Dashboard management page, click ADD DASHBOARD button. This will bring up a pop-up window to configure the new dashboard. A dashboard requires a name, descriptive location, description, and atype. The thumbnail is optional and if included needs to be 150100 pixels.

Customizing a Dashboard

Available Dashboard Widgets

Creating Custom Dashboard Widgets

When creating a custom dashboard, you have a blank canvas to place widgets onto of various sizes. The dashboard is a grid of 1x1 blocks in which widgets are placed and sized. Custom dashboards can be created with 2 columns or 3 columns (wide screen), which actually maps to 4 block width or 6 block width. The layout is set when adding a new custom dashboard.

With a new blank custom dashboard or one that already exists, users are able to use the 'Add Widget' button to select from a number of available off the shelf widgets or create a custom widget to drop onto the dashboard. Once widgets are placed, they can be moved around the gride. The '+' sign in the header of each widget allows the user to pick up the widget and move it.

Editing a custom Dashboard

Custom and editable dashboards allow you to configure what information and interfaces are shown in the form of widgets. Start by clicking ADD WIDGET at the upper-right-hand corner of the dashboard window. This will show a widget pop-up wizard to specify the type of widget and any configuration information. Exosite widgets can be interactive to the user and may make calls to other widgets. For example, a list of data sources may allow the user to select one or multiple to show on a graph widget next to it.

Sharing a Dashboard

Dashboards can be shared with other users publicly or if included in the plan, privately. When sharing publicly a dashboard has a public URL which can be provided to anyone, no need to log-in.

To share private dashboards, a specific user email must be entered, which will send an email to that user. The shared dashboard will show up in the users portal drop-down menu at the top.

Quick Sharing

Have something really interesting on a dashboard that you want to show a coworker, management, a buddy, etc? Well, you canpubliclyshare a dashboard URL by going to the dashboard's configuration pop-up and selecting the 'Make public' check box (shown below). The shown URL can be sent to others to view with-out logging in.

Warning: This puts your dashboards on the public internet for anyone to see.

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 Scripting Interface

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.

HierarchyThis 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 ClientA 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 DetailsWhen 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

We here at Exosite have done it before, so it is nothing to worry about. If you've accidentally made a widget that you suspect falls into an infinite loop and breaks your portals dashboard, this is the article for you.

Case 1:

Sometimes your Browser has got your back and can halt the script for you. If this is the case you will be confronted with a pop-up along the lines of:

Select 'Stop Script' and you'll find that you can suddenly interact with your Portals dashboard page. Find that misbehaving widget and proceed to delete it.

Case 2:

It is time to go manual. Maybe your browser can't detect the issue, or it is to serious for the browser to recover. Regardless of the reason, you now need to intervene. What you need to do is halt the browser's loading of the page before it has time to reach the infinite part of the delinquent script. This is best done by starting to load the page and pressing the small 'x' near your browser's URL or Omnibar before the page can be completed. This might take a couple of tries to get just right, but if you have done it correctly you will see that the widget container is not loaded but the 'manager bar' can be interfaced with. Here is an example using the same dashboard as the image above, but properly interrupted.

If you need a refresher on where the 'x' or 'Stop-Loading-Current-Page Button' lives, it is the little 'x' that shows up when you are loading a page. Try refreshing any page and pay special attention to the top bar of your browser. Here is also a picture of what it looks like in the Chrome browser.

Best Practice Tips:

-Keep a copy of your widget scripts in a different location. Github or a local directory are great places to keep a copy of a script while you are developing within Exosite.

Up & Coming:

- A Custom-Widget API to update and change scripts from an environment besides the dashboard page.

The Exosite One Platform's fundamental elements are clients which represent devices in the cloud. A device client contains resources like data sources, scripts, and meta information and is accessed by using a CIK (Client Identifier Key) to read, write, and modify it.

Clients Overview

The simple scenario is for a user to 'add a device' using a user application like Exosite's Web Portal, which would generate a new client with a CIK. The user can add data sources to it, scripts, and other resources and copy the CIK (which is a 40 character hash) to the device's application code. This is known as a 'generic' device client. This scenario works great for development and prototyping, but if you are a vendor and want to deploy a fleet of 1000's of devices, it's not a great solution.

This brings us to the idea of Client Models. A client model is a pre-defined device profile that a vendor would create. This device profile copies an original 'clone' whenever a user adds a new device of this client model type. Besides creating this copy automatically for the owner, the device can use the Exosite provision API to activate and receive the CIK automatically without any manual copying of the CIK to the device.

Exosite Provision Interface

Managing Client Models in the Portals Admin Interface

Starting on Device Client Software - Check List

Client Model Overview

Provisioning API - Vendor Fleet Management

Details

Client models are unique to vendor accounts, which is a prerequisite to create client models. Each client model has the following attributes:

Unique model identifier

Friendly name for users to see

Clone device

List of serial numbers

Content (Optional)

Groups (Optional)

Getting a Vendor Account The CloneThe clone is a generic device that has been set up with data sources, data rules, scripts, and dispatches that the vendor wants to copy each time a user application adds a new device. Serial NumbersThe serial number list is a 'whitelist' essentially of unique identifiers for devices that can be added by an owner. The serial number is typically dictated by a unique hardware identifier the device can use for API calls. Typically this is a Ethernet/WiFi MAC address or some other software readable identifier. The user application then asks the user what device they want to add and tells them to provide this unique identifier.When a device activates using the provisioning API, it will call in with the vendor id, model id, and this unique identifier. If an owner has enabled this unique serial number (added it) then the One Platform will provide a CIK to the device in response to the activation request.ContentContent is essentially files that can be posted for this client model with a file identifier, the blob (actual content), a description, and a timestamp. Devices can then use the provision API to get content, look for updates and decide to download the content. This is useful for things like updating firmware and applications in the field, configuration files, and posting media files for devices to download.GroupsTaking content to the next level, groups can be created that specify what serial numbers can access what content. This is useful for controlling access to certain content, perhaps if device owners have a license for more advanced features of your device.

Developers

Developers can use the provision API or the Portals Admin tools for managing client models. Managing Client Models in the Portals Admin Interface

Provisioning API - Devices

Here are the steps to creating and managing your client models from a developer stand-point.

Step 1. Create Clone

In a Portal for your whitelabel (sub-domain, domain), create a generic device and set up data sources, events (data rules), and scripts as you want every device (product) that is of your model to have. Any device that provisions as that model type and is enabled into an account will copy (clone) that setup including any data inside of data sources. Mark the device as a clone in it's Manage pop-up window. (There is a check-box for this)

Step 2. Create Model Type

As a whitelabel admin, you will have access to the Client Models area of the sub-domain / domain. Add a new model and attach your generic 'Clone' from step 1 to this model type. Add your serial numbers (MAC address, MEID, etc) for your devices. Typically Serial Numbers are chosen by identifying a unique number on the device that software can read, as the device will need to try to activate with that unique number.

Step 3. Add Content for you Model Type (optional)

If you would like to make content (firmware, config files, media) available to your device to download after activating (provisioning), you may add the content after the client model type is created. This can be edited at any time. This is done at the admin level of a whitelabel account or via Vendor APIs.

Step 4. Put Code on the device that uses Exosite's Provisioning API

Provisioning allows for a couple of things. First is that it allows products to be put into the field without preprogramming CIK (Exosite Platform Keys). It also allows control of what uniquely listed devices (by serial number) can activate and get access to content. When a device tries to activate it sends it's Vendor ID, Model ID, and Serial Number to the Exosite Platform. The Platform will return with a response that denies the request or includes a CIK. The Platform will only allow a device to activate if the device's Serial Number has been Enabled (see next step). Optionally, the device's code (application) can also check for content using it's Vendor ID, Model ID, and Serial Number. The Platform will return with a list of content, timestamps, and sizes.

Step 5. Decide who or what will Enable devices

Devices that have had their Serial Number listed to the Model Type or will be auto-added must be enabled. This can be done through Exosite Portals (User Adds devices) or with API function calls from other software using your Vendor Key. This creates a ownership path of the device and data in the Exosite Platform. There is a default Time To Live (TTL) of 24 hours for device clients to activate once the Serial Number has been enabled.

Step 6. Power on devices

Devices that have been enabled will receive a CIK from the Exosite Platform when it attempts to activate (API call). The device should store this CIK in non-volatile memory, as it will use this for communicating with the Platform (read, write, RPCs, etc). It's recommended to have the device try to re-activate once in a while since devices may be re-enabled or ownership changed, which would generate a new CIK. The device will have access to any available content, which is also recommended to have a check for over a time period as it may be updated.

SMS Alerts are only available for Exosite Business accounts. If you are not yet a business customer, you can read more about our Business Tiers on our overview support page, or create a business account to review and purchase plans.

For business customers, the cost of text message alerts is billed to the businessaccount in increments of 10 text messages, based on monthly usage.

Setting SMS Usage Limits

Your Admin interface provides you with tools to place daily allowable limits on text messages to fityour business needs.

This daily limit is a 'safety' feature for developers and users. This sets a hard limit on how many SMS the One Platform will send out during a given day. This prevents unplannedusage (and charges), such as from scripts and event conditions.You can set the usage limits both on a plan level and on an individual portal level.

Plan Limits

When you create your domain plans (the options users are given to choose from when they sign up), you assign the resource limits for each plan. These settings are adjustable athttps://<subdomain>.exosite.com/admin/plans .

Portal limits

You can adjust the limits on individual portals at https://<subdomain>.exosite.com/admin/portallimits by selecting the intended portal and clicking on "Edit Limits."

You can also view (but not edit) a portal's resource usage athttps://<subdomain>.exosite.com/manage/settings within that portal's interface.

SMS not working?If you expect to be receiving an SMS alert but are not, it's likely that your Daily SMS limit is set to 0 or set too low and you may have already hit your daily limit.

This is a list of all of the widgets that are available in portals. Don't see what you need? Checkout the custom widget development page to make it yourself or contact us to setup a development agreement.

Bar chart

Takes each dataport, averages the data into bins of a specified window, and plots each average as a bar on a bar chart. This widget takes up to three dataports, each is binned and plotted separately.

Widget Features

Dataports

3

Datapoints

200

Widget Size

2x2

Caller

N

Callable

Y

Common Use Cases

Showing Aggregated Time Average Values, Showing Total Run-Time Per Hour

Big Number

Big Number displays the latest value of a single dataport in a large font with a color determined bypre-set thresholds.

ABig Number widget, is configured by choosing the threshold numbers for "Safe Level," "Warning Level," and "Alert"; the font color corresponding with each can be changed by changing the hexadecimal color code (e.g. #33CC00).

Widget Features

Dataport

1

Datapoints

1

Widget Size

Configurable

Caller

N

Callable

N

Common Use Cases

Showing current numerical status, with a color indicating its relationship to pre-defined thresholds - e.g., temperature or pressure.

Big Number - Simple

Takes a single dataportand prints it's latest value, big. Despite the name, it will display short strings as well, but this has a limit of about 5 characters in the 2 unit default width widget.

Widget Features

Dataport

1

Datapoints

1

Widget Size

Configurable

Caller

N

Callable

N

Common Use Cases

Showing Current Numerical Status such as Temperature or Air Quality

Data Source List

Lists selected data source name, value, and last reported time. This widget can be called from a caller widget, when called it will display the dataportsof the device selected in the calling widget.

Widget Features

Dataports

Unlimited

Datapoints

1

Widget Size

2x2

Caller

Y

Callable

Y

Common Use Cases

Viewing many dataports' current value quickly.

Device/Data Table

Lists devices selected individually or by type. Can also add columns to display common aliased dataportsfor each device. This widget can act as a caller widget.

Widget Features

Devices

Unlimited

Dataports

8

Datapoints

1

Widget Size

Configurable

Caller

Y

Callable

N

Common Use Cases

Viewing many devices' common dataportscurrent value quickly.

Device List

Lists all devices from a portal, including the current active state and event for each. This widget can act as a caller.

Widget Features

Devices

Unlimited

Widget Size

2x2

Caller

Y

Callable

N

Common Use Cases

Viewing many devices' active status and calling the data sourcelist widget or opening a device's domain dashboard.

Device Map

Shows the location of a device from the user-defined Location field.

Widget Features

Devices

Unlimited

Widget Size

2x2, 3x4, or 4x4

Caller

Y

Callable

N

Common Use Cases

Showing the locations of a fleet of vehicles on a map.

Device Trail Map

Shows map with the last known position and breadcrumb trail of past known locations of a single device.

Widget Features

Devices

1

Widget Size

2x2, 3x4, or 4x4

Caller

N

Callable

N

Common Use Cases

Showing the path of a vehicle on a map.

Event List

Lists device events, their status, and last occurrences.

Widget Features

Devices

1

Events

Unlimited

Widget Size

2x1 or 2x2

Caller

Y

Callable

Y

Common Use Cases

Showing the event status of a device.

Event Log

Lists a history of periods that an event was active.

Widget Features

Events

1

Widget Size

2x2

Caller

N

Callable

Y

Common Use Cases

Showing the historical event status of a single event.

Gauge

Shows the value of a data source on a configurable gauge.

Widget Features

Dataports

1

Datapoints

1

Widget Size

2x2

Caller

N

Callable

Y

Common Use Cases

Showing Current Numerical Status such as Temperature or Air Quality

Image Box

Upload a picture to show on your dashboard with optional message and caption.

Widget Features

Widget Size

Configurable

Caller

N

Callable

N

Common Use Cases

Show an Image of the Product

Image Multi Size

Reads image URL from selected dataport.

Widget Features

Dataports

1

Datapoints

1

Widget Size

Configurable

Caller

N

Callable

N

Common Use Cases

Show a status image generated by the device.

Image Overlay

Overlays data source values and active state on top of an uploaded image file.

Widget Features

Dataports

Unlimited

Datapoints

1

Widget Size

Configurable

Caller

Y

Callable

N

Common Use Cases

Show an image of the product with parameters overladed.

JSON Viewer

Shows editable JSON strings in a nested view.

Widget Features

Dataports

Unlimited

Datapoints

1

Widget Size

2x2, 3x4, or 4x4

Caller

N

Callable

N

Common Use Cases

Edit configuration parameters for device.

Line Graph

Shows current and historical values of up to 4 data sources plotted versus time.

Widget Features

Dataports

4

Datapoints

200

Widget Size

2x2

Caller

N

Callable

Y

Common Use Cases

Plotting values such as temperature.

Line Graph - Scrolling

Widget Features

Dataports

4

Datapoints

200

Widget Size

2x2, 3x4, or 4x4

Caller

N

Callable

Y

Common Use Cases

Plotting values such as temperature.

On/Off Switch

Writes to the selecteddataport as either 0 (off) or 1 (on). Set up dataport as an integer type.

Widget Features

Dataports

1

Datapoints

1

Widget Size

1x2, or 2x2

Caller

N

Callable

Y

Common Use Cases

Toggling condition of selecteddataport

Tabular Report

Shows a report of past data or events.

Widget Features

Datasources

1

Datapoints or Events

500

Widget Size

Configurable

Caller

N

Callable

Y

Common Use Cases

Plotting values such as temperature.

Tank

Shows a stylized view of the level of a tank.

Widget Features

Datasources

1

Datapoints

1

Widget Size

2x2

Caller

N

Callable

Y

Common Use Cases

Showing the level of a tank.

Text Box

A box, into which you can put text.

Widget Features

Widget Size

Configurable

Caller

N

Callable

N

Common Use Cases

Showing a custom welcome message or links for more information.

Welcome

This is a simple help widget that is part of the default configuration of a new dashboard. It contains a nice greeting as well as some links to helpful documentation.

Widget Features

Widget Size

2x2

Caller

N

Callable

N

Common Use Cases

Welcoming users to exosite.

The One Platform stores additional information related to devices (clients) or data sources (dataports) in the meta field of these two Platform resources.

Examples are the activetime value used in some widgets to show if a device is 'online' or not and the 'unit' field for data sources in portals.

Device (Client) Meta

The device meta field stores user-configurable data as well as important information about the device type.

Portals sets different information for generic clients and those based on Client Models.

Type: Client Model

{

"activetime": "<ActiveTimeRange>",

"timezone": "<Timezone>",

"location": "<Location>",

"device": {

"type": "vendor",

"vendor": "<VendorID>",

"model": "<ModelName>",

"sn": "<SerialNumber>"

}

}

Type: Generic

{

"activetime": "<ActiveTimeRange>",

"timezone": "<Timezone>",

"location": "<Location>",

"device": {

"type": "generic"

}

}

CreatingClient Meta

In order to create Client Meta using the Remote Procedure Call API (RPC), in the body of your RPC call, the Meta JSON object must be converted to a stringand included in the "meta" property, as shown below:

{"procedure": "create",

"arguments": [

<ResourceID>,

"client",

{

"limits": {

"client": number | "inherit" = 0,

"dataport": number | "inherit" = 0,

"datarule": number | "inherit" = 0,

"disk": number | "inherit" = 0,

"dispatch": number | "inherit" = 0,

"email": number | "inherit" = 0,

"email_bucket": number | "inherit" = 0,

"http": number | "inherit" = 0,

"http_bucket": number | "inherit" = 0,

"share": number | "inherit" = 0,

"sms": number | "inherit" = 0,

"sms_bucket": number | "inherit" = 0,

"xmpp": number | "inherit" = 0,

"xmpp_bucket": number | "inherit" = 0

},

"locked": boolean = false,

"meta": string = "",

"name": string = "",

"public": boolean = false

}

],

"id": 1

}

More information can be found in the RPC documentation for creating a device/client.

Data Source (Dataport) Meta

Portals has been configured to render data sources with a visibility setting of hidden in the data source meta field to not show up in the users data source listing page and in widgets.

{

"datasource": {

"description":"",

"unit":"unit"

}

}

CreatingDataportMeta

In order to create or modify Dataport Meta using the Remote Procedure Call API (RPC), in the body of your call, the Meta JSON object must beconverted to a string and included in the "meta" property, as shown below:

{ "procedure":"create",

"arguments": [

"dataport", {

"format": "float" | "integer" | "string",

"meta": string = "",

"name": string = "",

"preprocess": list = [],

"public": boolean = false,

"retention": { "count": number | "infinity", "duration": number | "infinity" },

"subscribe": <ResourceID> | null = null

}

],

"id": 1

}

More information can be found in the RPC documentation for creating a dataport.

Devices that have been created to connect with Exosite need to 'activate' to exchange a key so they can communicate with Exosite's platform in a secure way. This activation function also sets up a path of ownership for the device. When you add a device to your portal, you are creating the chain of ownership, you are 'claiming' that device so it is in your account and it's data can be seen by you.

For specific device issues, we recommend looking over user guides and device information provided by the Product OEM, Development Kit provider, or if using open source code, where that code is documented.

This will cover the generic overview of device adding issues.

For developers, check out our provisioning guide

Most common problems:

Enteringwrong unique number/ serial number / MAC address / MEID - Double check your number when entering it.

Adding a device stillowned (claimed) by someone else- Contact that person if you got it from someone else.

The vendor of the portal did not approve that unique number up yet to be used

Troubleshooting

If you attempt to add a device to your portal using a unique number (serial number, MAC address, MEID, etc) but receive an error message like the following, there are a few steps to resolve this.

You have attempted to add a <unique address> that is not approved for this device. This may be by error. Please verify the exact <unique address> of your device and if you believe it is correct, use the Feedback system to contact us

The first is to verify you have thecorrect unique identifier, which should be a serial number, MAC address, MEID, ESN or some other hardware identifier. This information should be provided by the device OEM and can usually be found on a sticker on a device or possibly through a LCD or serial port.

Double checkthe number you are using, check the format, check the sticker again for numbers that look like letters, etc.

The next issue may be that the device had beenclaimed by someoneelse either by mistake or previous ownership. Contact the OEM using the Portal HELP / support links to check this. They can quickly check this and help resolve.

Of course, there is always apossibly that the device is incorrectlyusing the wrong activation unique identifier number. This is a problem to work out with the OEM or code provider.

Welcome to Exosite Portals, the web application that lets people connect and manage devices and data. Portals is the user interface, the front end of the One Platform. This document walks through the steps for a new user using a community or development account.

Note: Many companies use Exosite's Portal tool for their own custom sub-domain like 'company.exosite.com' or as a full custom domain 'portal.company.com'. This is called a w hitelabel vendor account. Most of these custom versions will closely follow theinformation on this page and in general, the Portals Documentation, but could be different based on each implementation.

Sign Up for an Account

Its free to sign up and get a basic account. We try to make it as painless as possible.

If you have an account on an Exosite subdomain already,click the "Add it here" link (shown below) to login with your existing email address and password. This will add the new subdomain to your account. If you try to create a new account with an email address you've previously used to sign up for a Portals-powered website, you'll get an error.

dashboard

If you have never created an account on an Exosite subdomain before, follow the instructions below to create a community Portals account.

Sign-up on portals.exosite.com >>

To sign up, you need only provide your email and your first and last name, and verify that you have read and agree to Exosite's Online Service Agreement. You will log in using the email you provided at signup; you can set your password and an optional security question later in the process.

Shortly afteryou sign up, you'llreceive a confirmationemail with instructionsto finish setting up your account. If you do not receive an email, please check your email spamfilters; if you still cannot locate the email, contact [email protected] for assistance.

The confirmation email will contain an activation link and a temporary password, both of which are necessary to log in to your account for the first time. If you get an "invalid key" error when clicking the activation link, it's often because the link has already been clicked; try logging in with your email and temporary password.

Log-in

Log-in at the following address: https://portals.exosite.com (or at your subdomain).

The first time you log in, you must use the temporary password provided to you in yourconfirmation email.

Change your password or security question

Once you have successfully logged in to Portals, you may want to change your password, or add or change a security question as an added measure. This can be done by accessing your Account pagefrom the dropdown menu under your name in the upper right-hand corner of the page.

From the Account page, you can update your profile information, change your password, add a security question, or cancel your account.

First Dashboard

The first time you log-in to your new account, you will be brought to athat has been pre-configured to have a few widgets. One is the welcome widget that has some handy tips and information. The Data Source list widget lists the data sources currently for your account and weve included a few public data sources so you have something interesting to look at and play around with. Youll find that if you select a data source here, the bottom gauge widget will change to that specific data source.Dashboards are configurable, so at any time this default dashboard can be changed, widgets deleted and added. Click on the little upside down triangle box for each widget to edit it.

Try out adding a new widget. Click the Add Widget button in the upper right-hand corner, which will bring up a pop-up wizard.

Select Widget Type Line Graph

Type in a name like Line Graph 24 hours

Click the Continue button

Click on a data source under the list of data sources to be the default active selection.

Set Caller as Portal Data Source List

Set Refresh rate to 60 seconds

Click the Submit button

Click the Quit button for the widget wizard

Management Interface

Now that you are acquainted with dashboards, lets focus on the management interface. On the left hand side of the screen there is a floating menu that says Manage at the top. These links take you to the different management areas of Portals. To add a new device client, click Devices. To manage dashboards including who can see them, click Dashboards. You get the idea.

Home: Always brings the user back to the default home dashboard page for a specific portal.

Data: Add, configure data sources, export data.

Devices: Add, configure device clients.

Events: Add and manage events and alerts.

Dashboards: Add new dashboards, manage user access to view.

Scripts: Add and manage client scripts

Settings: This portals management, including choosing default dashboard and adding manager level users

Start:This is a custom dashboardavailableto users of portals.exosite.com, with widgets to get you started with Portals.

One other quick note, at the top youll find a drop-down menu (the down triangle) that allows you to look at all portals and portal dashboards that you have access to. Your current portal will be listed first and if other users share portal or viewprivileges, these will be accessible here also. The Default is the portal and to the right, user name is your dashboard, which in this case is your only one so far. By adding a second dashboard, this would be accessible from this drop-down.

Note: This article contains advanced usage of both the One Platform scripting and Portals widgets.

IntroductionA very typical need of almost every device used on Exosite is alerting if it is online or not and being able to check if your devices are online. The specific items required usually involve the following:Determine a timeout condition (the device is off-line)Alert something or someone of timeout conditions / Take actionShow device online status What Portals DoesPortals tries to give you an indication of this for you. For example, on portals.exosite.com/manage/devices page, you should see a list of devices, a green or red dot indicating if it is online or not, and a 'Last Reported Time' category. Here is an example image of that:

domain widget

Portals calculates 'Active' by looking at the 'Active Time' field that is stored in the device's meta information. This 'Active Time' is not a specific item of One Platform clients, but Portals adds it into the Device client's meta info, as an application detail. That field is by default 5 minutes if you add a device through Portals and you can edit it if you click on the device here and open it's 'pop up' window. ( More information about how Portals stores application specific info can be found here ).

Portals also calculates this 'Last Reported Time' based on the last value of any data source, no matter if the device actually wrote it or a script or a user wrote to a data source using a widget, so it can be misleading.

Creating a Timeout Events and Alerts in PortalsPortals also let's me create simple Events and Alerts, one of which is condition type 'timeout'. Here you can see in the graphic below how a simple wizard interface walks me through creating an event, which in the One Platform is a 'data rule'. This event is false until it detects that the selected data source hasn't reported data in the duration specified, in this case 60 seconds, at which point the event is true. I can then attach an 'alert' to this event on the same page. An alert is a 'dispatch' in the One Platform.

Improved Timeout / Status indicationSo, how can this be improved for my application? There are two parts to this document, one on creating a more advanced timeout detection and handling feature. The other is a more customized dashboard widget that is specific to your application needs. We'll detail both here below.Create a Timeout / Status ScriptA One Platform script has access to all information and resources of a client (device). This means that you can write your script to tailer the timeout condition and status reporting. Let's say your device is reporting multiple pieces of information, but only one data source really matters and tells you if it is online or not. We'll call this data source 'packet'. Let's also say you want to have alerts and widgets be able to communicate information like the last time you received the packet, how long it has been timed out if it has timed out, etc.Here are the data sources I want to examine and/or write to with information.

packet - This is the actual data coming in from the device, it's the only thing that I care about determining if it is online or not

status - This data source will be used for alert messages and for a widget to tell me if the device is online, timed-out, how long it has timed out, etc

lastpacket - This data source will store the last reported timestamp of packet. (Yes I could get this from the packet data source but it handy for widgets and alerts to have as a data source.

My script will do the following things:

Create these data sources if they don't exist already

Set default values of status and lastpacket.

Get meta information about the device that Portals specified (active time period, timezone, etc)

Check every 60 seconds for new data into packet.

During this loop, get the last reported time of packet and compare against the current time.

If the difference between current time and last reported timestamp is greater than the Portals specified 'Active Time' field, update the status data source with the text 'Timeout' and also specify how long it has been in this timeout condition.

Write the last reported timestamp to lastpacket in human readable format.

Send an email alert out if the condition (online again or timeout) is new with information about the state.

Here is my script:

-- Advanced Timeout Alert and Status

-- Exosite One Platform Script

--

-- Script check if data received on packet to

-- determine activity / status of the device.

--

local device = alias[''] -- Represents this client device

local meta = json.decode(alias[''].meta) -- decode meta from device client

local dev_tz = meta.timezone -- device timezone as specified by Portals field

local dev_location = meta.location -- device location as specified by Portals field

local dev_acttime = meta.activetime -- device active time as specified by Portals field

-- User / Application preference settings

setlocale("en_US.utf8")

settimezone("UTC")

local timeformat = '%b %d,%Y %T %Z'

debug('starting')

debug('Name: '.. device.name..',Active Timeout: '..dev_acttime..'m')

--

-- This is a list of data sources used by this script and

-- this table is used to check and create if they don't exist

--

local dstable = {

{alias="packet",name="Packet",format="string"},

{alias="status",name="Status",format="string"},

{alias="lastpacket",name="Last Packet Time",format="string"},

}

--

-- This is a routine that will check if data sources exist and

-- if not create

--

for i, ds in ipairs(dstable) do

if not manage.lookup("aliased",ds.alias) then

local description = {

format = ds.format

,name = ds.name

,retention = {count = 1,duration = "infinity"}

,visibility = "private"

}

debug("creating datasource: "..ds.name.."(alias: "..ds.alias..")")

local success,rid = manage.create("dataport",description)

if not success then

debug("error initializing rid dataport: "..rid or "")

return

end

manage.map("alias",rid,ds.alias)

end

end

-- Function to send alert

local function sendalert(state,detectedtime,lasttime)

local emailaddress = 'emailaddresshere'

local emailsubject = ''

local emailmessage = ''

debug('sending alert')

emailsubject = 'Alert: State Change: Device: '..device.name

emailmessage = 'Detected State Change at %s\r\nDevice Name: %s\r\nLocation: %s\r\nNew State: %s\r\nLast Reported Time: %s\r\n'

emailmessage = string.format(emailmessage,detectedtime,device.name,dev_location,state,lasttime)

-- Send Alert Message

local status,reason = email(emailaddress,emailsubject,emailmessage)

if status == false then debug('Email failed, reason: '.. reason) end

end

-- Get variables for specific data sources to check/write

local packet = alias['packet']

local status = alias['status']

local packettime = alias['lastpacket']

local state = 'na'

-- Let user know that the script is checking status now

status.value = 'Checking..'

debug('starting routine loop')

while true do

local ts = packet.wait(now+60) -- run this loop every 60 seconds no matter if new data or not

meta = json.decode(alias[''].meta) -- update meta data, which is in json format

dev_acttime = meta.activetime -- update active time

local p_ts = packet.timestamp

if p_ts ~= nil then

if (now - p_ts) > dev_acttime*60 then

if state ~= 'timeout' then

status.value = 'Timeout (>'..dev_acttime..' m)'

packettime.value = string.format('%s',date(timeformat,p_ts))

debug('timeout (>'..dev_acttime..' m) '..string.format('%s',date(timeformat,p_ts)))

state = 'timeout'

sendalert(state,date(timeformat,now),date(timeformat,p_ts))

end

else

if state ~= 'running' then

state = 'running'

status.value = 'Running'

debug('running - '..string.format('%s',date(timeformat,p_ts)))

sendalert(state,date(timeformat,now),date(timeformat,p_ts))

end

packettime.value = string.format('%s',date(timeformat,p_ts))

end

else --no data at all, no timestamp

if state ~= 'timeout' then

status.value = "Has not reported"

packettime.value = string.format('never')

debug('timeout (>'..dev_acttime..' m) '..string.format("hasn't reported yet"))

state = 'timeout'

sendalert(state,date(timeformat,now),'never')

end

end

end

When this runs, I get an email like this with a state change (timeout detected or data written to packet after timeout).

Create a Custom Status WidgetOn to the device list widget. We saw what Portals offers on the /manage/device page. There is a 'Device List' widget that is off the shelf and as of writing this document looks something like this, where 'Active' shows as Green or Red depending on last written value of any data source. Another off the shelf widget is the 'Device Data Table' widget. These are shown below, one the Device Data table widget I'm showing the two data sources I created in my script (status and lastpacket).

Portals Off-the-Shelf Widgets

Let's build a widget that is specific to my application need. First, let's add a custom widget to my dashboard.

I want to have columns for the device name, status, last packet, and some data sources. Custom widgets are written in Javascript and in this example, I'm going to take advantage of the Google Chart APIs.

Here is what this custom widget looks like.

Here is the custom widget javascript code

/**

* Table

* @version 1.0.0

*/

// select one or more data sources from the list above to view this demo.

function(container,portal)

{

//console.log("starting sensor table widget")

function errorMsg( message )

{

var h3 = document.createElement('h3'),

strong = document.createElement('strong'),

p = document.createElement('p')

;

container.appendChild( h3 );

h3.appendChild( strong );

strong.innerHTML = 'ERROR:';

container.appendChild( p );

p.innerHTML = message;

container.style.margin = '20px';

container.style.color = '#a60000';

}

function addCSSclass(className, classRule)

{

if (document.all) {

document.styleSheets[0].addRule("." + className, classRule);

}

else if (document.getElementById) {

document.styleSheets[0].insertRule("." + className + " { " + classRule + " }", 0);

}

}

function googleChart( portal )

{

var i,

d,

group,

output = { cols: [], rows: [] },

devicemeta,

deviceclient,

ds,

packet,

lastpacket,

status,

statusFormat,

statusVal,//0 unknown, 1 running, 2 timeout

rowFormat//default

;

console.log("start through device list");

for( d = 0; d < portal.clients.length; d++ )

{

//default values for each client

lastpacket = "n/a";

packet = "n/a"

status = "n/a";

statusFormat = '<img src="' + '/static/png/indicator_grey_lamp.png'

+ '"'+'style="vertical-align:middle"'

+'/> '+'not available';

statusVal = 0;//0 unknown, 1 running, 2 timeout

rowFormat = 'line-height:1em'; //default

group = [];

deviceclient = portal.clients[d];

devicemeta = JSON.parse( deviceclient.info.description.meta);

for (i = 0; i < deviceclient.dataports.length; i++)

{

//console.log(i)

//console.log(deviceclient.dataports[i].alias)

ds = deviceclient.dataports[i];

if (ds.alias == 'lastpacket')

{

try{

lastpacket = ds.data[0][1];

}

catch(err){

lastpacket = "error";

}

}

if (ds.alias == 'packet')

{

try{

packet = ds.data[0][1];

}

catch(err){

packet = "error";

}

} if (ds.alias == 'status')

{

try

{

status = ds.data[0][1];

if(status.search("Running")==-1)

{

//statusFormat = '<img src="' + '/static/png/not_available.png' + '"/>'

statusFormat = '<img src="' + '/static/png/indicator_red_lamp.png' + '"'+'style="vertical-align:middle"' +'/> '+status;

statusVal = 2;

//rowFormat = 'background-color: #f8cccc; font-weight:bold; line-height:1em';

//rowFormat = 'font-weight:bold; line-height:1em';

}

else

{

//statusFormat = '<img src="' + '/static/png/available.png' + '"/>'

statusFormat = '<img src="' + '/static/png/indicator_green_lamp.png' + '"'+'style="vertical-align:middle"' +'/> '+status;

statusVal = 1;

}

}

catch(err)

{

statusFormat = '<img src="' + '/static/png/indicator_grey_lamp.png' + '"'+'style="vertical-align:middle"' +'/> '+'error';

statusVal = 0;

}

}

}

//console.log("Create Row");

group[0] = { v: deviceclient.info.description.name, p:{style:rowFormat} };

group[1] = { v: statusVal, f: statusFormat, p:{style:rowFormat}};

group[2] = { v: lastpacket, p:{style:rowFormat}};

group[3] = { v: packet, p:{style:rowFormat}}

group[4] = { v: 'interesting data', p:{style:rowFormat}};

group[5] = { v: '1024', p:{style:rowFormat}};

output.rows.push( { c: group } );

}

output.cols.push( { label: 'Device', type: 'string' } );

output.cols.push( { label: 'Status', type: 'string' } );

output.cols.push( { label: 'Last Packet', type: 'string' } );

output.cols.push( { label: 'Packet Value', type: 'string' } );

output.cols.push( { label: 'Other Data', type: 'string' } );

output.cols.push( { label: 'More Data', type: 'number' } );

addCSSclass("bold-font", "font-weight: bold;");

// draw google chart

google.load( 'visualization', '1',

{

packages: ['table'],

callback: drawChart

} );

function drawChart()

{

var cssCustom = {

'headerRow': '',

'tableRow': '',

'oddTableRow': '',

'selectedTableRow': '',

'hoverTableRow': '',

'headerCell': '',

'tableCell': '',

'rowNumberCell': ''},

data = new google.visualization.DataTable( output ),

view = new google.visualization.DataView(data),

table = new google.visualization.Table( container ),

options =

{

width: '100%',

//height: '100%',

//showRowNumber: true,

alternatingRowStyle:true,

allowHtml:true,

page: 'disable',

pageSize: 5,

pagingSymbols:

{

prev: 'prev',

next: 'next'

},

pagingButtonsConfiguration: 'auto',

sort:'enable',

sortAscending:false,

sortColumn:1,

cssClassNames: cssCustom

}

;

//view.hideColumns([3]);

table.draw( view, options );

google.visualization.events.addListener(table, 'select', function() {

var row

;

row = table.getSelection()[0].row;

table.setSelection();

alert('You selected ' + data.getValue(row, 0) +'\r\nCould use this to go to another page or change other widgets');

});

}

}

// return if no data sources are selected.

if( portal.clients.length < 1 )

{

errorMsg('No Devices Available');

return;

}

// google chart

googleChart( portal );

}

Here is a look at my dashboard showing each of these widgets (off the shelf vs my new custom widget) for a comparison. (Note I can change the size of the custom widget)

See how the 'My Devices' widget (device list widget) shows that both devices are active because a data source for both has been written to in respective active time period. For my application need, I only want to know if the data source 'packet' has been written to, which my custom widget tells me.

If I am domain admin (portals solution), I can actually then create a from this custom widget code that I can publish and use including auto populating device and data sources without having to select what is available in the custom widget editor.

That's it. Hopefully this is useful when thinking about your application needs.

Each Portal Solutionsite can change it's theme including the header, footer, color scheme, and really about any HTML CSS items available. Some of the theme options are available with-in the tool as easy configurable color pickers and image uploads. Using the 'CSS rules' area allows you to completely customize any CSS you want. Add a new themeTo create your own theme, you'll first want to go to your Portal Solutions admin area and clock the 'Theme' option under Domain Setup in the domain admin menu. Example Header Background Tile File Edit your new theme by selecting it in the 'Select Theme to Configure' drop-down list. Once you are satisfied, you can set your new theme to as the theme used by the subdomain site by clicking 'Set Default' next to your theme. You can create as many themes as you want.After switching the default theme, you should see your changes instantly.

A Portals Solution domainowner has the ability to control the theme and branding of theirsolution. Admins can use the Theme editing tools to choose color schemes and uploading images for specific style objects. For full customization, the Admin is also provided with a box to specify their own CSS rules.

Editing a Theme

To edit a theme, go to your admin tools and under Domain Setup you will find the 'Theme' page. If you haven't already, add a new theme and then use the Theme Configuration drop down menu to start editing it. Note, unless your theme is selected as the default, you will not see changes real-time.

You'll see there are a number of elements of the them that you can change using easy color selection tools, text boxes, and file uploaders.

Header

The header area of portals requires a background image of height 82 pixels. The image file that must be uploaded must be a widget of 62 pixels (image size should be 62x82 pixels) and will be tiled across the entire header of the page.

The logo file must be 300x82 pixels and will be put into the upper-left corner. We recommend using a transparent png file so that the background image shows through.

Examples of each of these files can be found attached to this article.

Example Logo file

After applying these files to a theme, the header would look like this:

Custom CSS

To completely control your CSS, you can enter custom CSS rules at the very bottom of the theme editor.

The format for this is the same as CSS files, which makes it handy for editing. After changing the custom CSS rules, hit 'Submit' to apply changes.

Note: There is no undo function, so it is recommended to save a separate backup file on your computer)

What elements are customizable using custom CSS rules?

All elements are customizable. The best way to determine what to change for an element is to use your browsers debug tools. Most browsers (Firefox, Chrome, etc) have a tool built-in that allows you to see the HTML and CSS for web page elements. Usually this is available by right-clicking your mouse on the item. Here is an example of inspecting the log-in button using Firefox.

You can see that after performing this on the log-in button, the browser shows me a window that shows the html and css for this page, specifically for the log-in button element.

I can now copy this CSS and paste into my Custom CSS Rules in the theme editor to make adjustments to it.

Example - Change Button Style

Let's change the default style of the buttons used in Exosite Portals. Typically this is a gray gradient. In our case, we want to change this to match my theme. By pasting the following CSS code into the theme editor's custom CSS rules box and submitting this, the button style will be changed.

.exosite-button {

border-radius: 4px;

border: 0px;

border-image-source: initial;

border-image-slice: initial;

border-image-width: initial;

border-image-outset: initial;

border-image-repeat: initial;

font-size: 14px;

background: #E05C04;

color: rgb(255, 255, 255);

}

.exosite-button:hover {

background: #E05C04;

color: rgb(255, 255, 255);

}

Example - Remove Widget Block Outlines

If I wanted to remove the edges of the widget blocks for example, I could do that with the following code:

form#loginform>div.block,

div.block

{

background-color:transparent;

border:0px solid #E5E6E6;

padding:0.0em;

}

div.block .blockcontent .title

{

background-color:transparent;

font-size:0.9em;

font-weight:bold;

margin:0;

padding:0 1em;

text-align:left;

}

div.block div.blockcontent div.content

{

border:0px solid #E5E6E6;

padding:0 1em;

background-color:rgb(249, 249, 249)

}

Example -Customize Buttons

If you'd like to change the style for your buttons in your Whitelabel account, edit the subdomain's theme by going to your subdomain's theme editing page(e.g. http://<yoursubdomain>.exosite.com/admin/theme) and editthe User Defined CSS rules.Here is an example of changing the theme for your site buttons:

.exosite-button {

border-radius: 4px;

border: 0px;

border-image-source: initial;

border-image-slice: initial;

border-image-width: initial;

border-image-outset: initial;

border-image-repeat: initial;

font-size: 14px;

background: #8A56A3;

color: rgb(255, 255, 255);

}

.exosite-button:hover {

background: #8A56A3;

color: rgb(255, 255, 255);

}

In any place you can use custom HTML (admin configuration of pages, custom widgets, etc) you can use these buttons like this:

<a class="exosite-button js-exosite-button" href="http://www.exosite.com/" id="button-signup" type="button">CUSTOM ACTION</a>

This would add a button that looked like this:

Many developers manually add their devices through the Add Device wizard in Portals. However, sometimes it is necessary or more user-friendly to pre-create a URL that, when launched, will automatically add the device to the Users Portal.

The URL structure in Exosite Portals to do this is:

/manage/devices?new&enable&vendor=<vendor>&model=<model>&sn=<sn>&name=<name>&alias=<alias>&location=<location>

for example:

https://portals.exosite.com/manage/devices?new&enable&vendor=acme&model=fake&sn=123&name=Widget&alias=demo&location=Minneapolis

This will do functionally the same thing as if the user clicks +Add Device at /manage/device and enters the information manually.

The main requirement, other than the parameters being correct, is that the user who launches the URL is logged into Portals.

The parameters are:

vendor: The vendor name of whoever is providing the device / client. e.g. acme.

model: The unique model ID of the device / client. Cannot, at current time, be generic must be an actual configured device model provided by the vendor.

sn: Serial number of the device / client. This will sometimes be a MAC address, but is model-specific as defined by the vendor.

name: Friendly name of the device / client. This is the name that users in Portals will see for the device / client.

alias (optional): Alias of the device / client. If no alias is specified, sn will be used as alias by default.

location (optional): Location of the device / client. This is the location that users in Portals will see on the Device pop-up of the device / client.

Question:

Why doesn't my device show up as 'Active', the 'Active' indicator is red instead of green?

Answer:

The Active status of devices is native to Portals, not the One Platform. The active status is determined in Portals by what the last reported time-stamp of data is versus the Active Time setting is in the device's Pop-up manage window. That Active Time setting gets stored in Meta Information for that device (client) in the OneP. ( How Portals uses Meta Information )

If your device is 'red' (not active), it is one of two things. One is that the device isn't actually sending data anymore and the last data (if ever sent) was more than the activity timeout. The second might be your device is sending data, but at a rate that is slower than your activity timeout setting. The default is 5 minutes, but can be changed in the device's pop-up manage window.

Question:

Is it possible to create custom widgets?

Answer:

Yes! You can use the 'Custom' widget type when selecting a new widget to add. You can edit the size of the widget block, what data it has access to, and enter your customer code in (you can also start from a number of templates which are selectable from a drop-down men).

Portal's Custom Widget Documentation

Question:

Can I change the Theme of my Portal account?

Answer:

Whitelabel customers (sub-domain or domain) can control the theme of their Portal sub-domain including header logo, header background, menu colors, page background, links, widget colors, and a number of other theme/branding/config items. Actually, you have full access to the CSS so you can change almost any of the web page theme. Whitelabel is perfect for vendors, OEMs, and companies to create their own product experience for their users.

Whitelabel sub-domain sign-up

Question:

What browsers are supported?

Answer:

There are many browsers that exist today, not only on standard computers but also on phones and tablets. Each of these browsers has new and old versions that may or may not support standards in web content coding. Our general statement is that Exosite Portals should work on all browsers based on our coding style, but it is almost impossible to guarantee support on every browser on every device and every version of it. We do our best to support the most commonly used browsers, please find the following list as a rule of thumb for what we recommend.

Recommended Browsers that are tested after releasesregularly:

Chrome Desktop most recent version (chrome is auto-updated)

Firefox Desktop most recent version (firefox is auto-update)

Internet Explorer 8,9,10 (Windows only)

Browsers that should work but are not tested regularly:

Internet Explorer 11 (Windows only)

Safari

Safari iOS

This widget is expecting the data format to be: MinDec (Degrees, Minutes, Decimal Minutes) packed as DDMM.MMMM_DDMM.MMMM .

So, I'll use this example, which you see in the widget text but I'll elaborate on it.

If I found a location of 44.9791583,-93.2923983 (which is what you get from Google maps for the middle of our building location), this is the 'Decimal Degrees'. I can't then just move the decimal point. What I have to do is convert this to Degrees and Minutes. So, the '44' is the decimal degrees, and that is ok. Next is 0.9791583, which is decimal degrees and I need to convert that to minutes. That ends up being 58.7495 minutes. So the actual data I write is: 4458.749_-9317.544

http://boulter.com/gps/#44.9791583%2C-93.2923983

Here is a great little tool site I ran across for conversion (I included my example coordinates, we don't have any affiliate with this site)

You can see there, the values you are after is the 'GPS' coordinates.

It's possible we could expand upon this (data format for location in this widget) in the future, if there was a use case that required it. Also note, you don't have to specify anything in the units field for this data source, even though the instructions say to do that. This is no longer required.

If you are having an issue with your portal, you can privately share your portal account with a member of the Exosite support team. This article specifically talks about Exosite Support but please note that any @exosite.com user does not count against your portal user limits. When the issue has been resolved, you can just remove the team member. With that being said, we would like to point out that Exosite is serious about security and privacy. If we could simply access your account, we would not need you to add us as a Manager.

Step One: Go to Settingsunder the Manage menu.

portals.exosite.com/manage/settings

The Settingspage is also available at, or by adding /manage/settings to the end of your subdomainURL.

Step Two: Under the Portal Roles enter '[email protected]'.Step Three: Set the Role to Manager and hit invite user

At this point the Exosite Support Team Member has access to your portal and can aid in resolving issues.

When the issue has been resolved or assistance is no longer needed, you may remove the team member by going back into portal roles and clicking on the remove box next to the users name.

Per-Device Limits

By default, purchased device resources have a limit of:

Up to 10 megabytes of data stored on our platform.

Data is retained for at least two years.

If you need more data storage or longer retention periods please contact us and we'll be happy discuss options with you which include moving to your own Portals solution.

Per-Datapoint Limits

Each datapoint, depending on the type, has a limit of:

String: 64 KB UTF-8 String.

Integer: Signed 64 Bit Integer: 9,223,372,036,854,775,808 to +9,223,372,036,854,775,807

Float: Single-Precision Floating-Point Number: 8 bit exponent and 24 bit significand precision (23 explicitly stored)

Binary: 64 KB Binary Blob (Deprecated, Use Base64 in a String)

When developing connected products, one of the first things to decide on is the data that is needed to be sent/read from it and what this format is. Exosite refers to this as the data architecture and there are many factors that need to be decided upon.

Exosite's One Platform holds data in time-series objects called dataport resources. Each dataport can store many values/timestamp pairs, dependent on the retention settings for the specific dataport and the client object it is a part of. The dataport resources are grouped under a client which represents the physical device or other entity.

Dataports can be of type int, float, or string. Strings can hold formatted data (formats such as JSON, XML, CSV).

Some examples showing the timestamps / values may look like:

Integer

1253408461

42

1253408460

41

1253408455

40

1253408440

41

12534084439

41

Float

1253408461

42.3

1253408460

41.2

1253408455

40.9

1253408440

41.4

12534084439

41.5

String

1253408461

forty two

1253408460

forty one

1253408455

error01

1253408440

starting again

12534084439

String - formated string

1253408461

{"temperature":42}

1253408460

{"temperature":41}

1253408455

{"temperature":40}

1253408440

{"temperature":41}

12534084439

{"temperature":"error"}

What format should be used?

That question needs to be answered by looking at how the data is used, how the data is created, and how the data is sent.

The One Platform's provisioning interface supports posting content under a client model. All devices that are activated under a client model have access to this content. The content area hosts files that can be used for such things as firmware, configuration information, media, etc.

Provision API

Device Interaction

The device interaction includes the following calls which are supported by our HTTP API and CoAP API.

List Available Content

Get Content Info

Download Content

Administration

Vendors can use the Provision API or the Portals Admin interface to post and edit content for client models.

Portal's Event Overview

Portals provides a management interface for the Data Rule and Dispatch resources of One Platform Clients and calls these Events and Alerts. Events (Data Rules) are triggered true or false resources, much like Data Ports (Data Sources) hold time series data. Data Rules can only be in a state of 1 (active) or 0 (inactive). Within Portals a user can add new events, edit them, and use different visualization widgets within dashboards to show event periods and status. Not only can it be important to see when and for how long a condition occurred, but also to trigger some action, like an email alert.

The data rules used by events have a set number of logical conditions which the Portal's event setup wizard walks the user through.

More complex event conditions and alerts can use scripting

Thinking about a basic event condition on temperature data, an event could be set up to look for a condition in which the temperature is below a value, lets use 40 degrees. Perhaps you want to know when this happens and how long, so the logged activity and timeline graph is important to look at. You may also want to be notified of this using an alert, say receive an email.

The Portals Event creation includes the following event condition types:

Event Types

Simple

True while the condition is met, False otherwise.

client resources

Timeout

True if no data has been received for the duration specified, False otherwise

Duration

True if the condition is met for the specified duration, False otherwise.

Count

True if the condition is met the number of times specified by the Count Limit during the specified duration, False otherwise.

Adding a new Event

Lets assume no events or alerts have been set up. Your screen should look something like the image below.

Lets add a new event and assume there are active data sources, most likely the default public temperature data sources that are added with each new account. Start by clicking the Add Event button. At wizard box should open up and look like this figure. Choose the data source you want to event on. Click Continue.

Next give the event a name, for example Cold Temperature in this diagram. Select a event condition type, like Duration as shown here. The duration event type looks for the event condition to be true for some amount of time. In this example the comparison is Less than or Equal to. You might ask why we use a duration, in this case I know that temp data can sometimes hover around a value going back and forth just slightly. By asking for a duration, it essentially lets the value settle, so that the event condition does not trigger multiple times in a short span of time.

Click Continue and you should see this new event added to your list on the event page.

Clicking on an event will open a configuration pop-up window that shows logged information on the event and a timeline graph.

Thats it, you have a new event.

Alert Overview

Alerts are dispatch from the platform, triggered by a logica data rule (event) or a script. Within Portals a user can add new, edit, and check logs of alerts. These can be useful to be notified that an event condition has occurred. Multiple alerts can be created for an event, perhaps if notification needs to go to multiple individuals.

Alerts available to users in Portals include email and SMS text messages. Other dispatch alerts are available for developers from the Platform using API or scripting functionality

Important Note: SMS Phone Numbers should include the +1 (country code) at the beginning. (e.g. for a US number: +16121234567 for 612-123-4567; for a Taiwan number: +886912345678 for 0912-345-678)

Adding a new Alert

Now with an event created (you can not have an alert without an event). Your screen should look something like the image below. Lets add an alert.

Start by clicking the Add Event button. At wizard box should open up and look like this figure. Choose the event you want to alert on. Click Continue.

Next give the alert a name, for example Cold Alert in this diagram. Set the interval, which is the time period in which it will resent the alert if the event stays true. (Be careful with the interval, if you set it at 5 seconds, youll get your alert every 5 seconds). Thesuggested value is 0, which will only allow it to be sent once, when the event first becomes true.Select an action, like email or SMS. (Your plan may or may not include SMS) Set the contact information, in this example an email address, the email subject and email body message.

Click Continue and you should see this new alert added to your list on the event page.

Clicking on an alert will open a configuration pop-up window that shows logged information on the alert and a timeline graph.

Thats it, you have a new alert.

Overview

In order to use Client Models and Device Provisioning for your Devices, the Exosite Vendor Management interface must be used to configure and define how the interface will work for your Device (Client) Model. The Vendor Management interface is accessible via the Exosite API and by using the admin interface in Exosite Portals Whitelabel accounts.

To access this vendor management interface through Exosite Portals, domain-level administrative access is required. This is most commonly accomplished by using our Whitelabel plan. Get started on your own Whitelabel account here or contact us to get signed up for your own Portals Domain-level Interface we can get you going in less than an hour.

Further Reading

Provision API - Vendor Management Functions

How do I get a Vendor ID and Account?

User Guide for Whitelabel Admins Manufacturing Notes for Vendors The Management Interface

The vendor interface is available with the Exosite API and by a web user interface using Exosite Portals with admin access. Here is a video showing how to create a Client Model in the web interface:

Vendor Functionality

Create Client ModelsVendors are able to create and update Client Models with their Vendor ID. The Models are unique to their vendor account. Each model has an unique model identifier that is used both by devices attempting to activate or get content and by applications that allow for interacting with the client model.Each client model is cloned from an original generic device that is set up with data sources, data, scripts and other platform resources. Manage Serial Number ListsVendors manage client model serial number lists through the provisioning management API. The way a device is identified as a specific instance of a client model is through a Serial Number. The serial number can be any unique identifying value of numbers and letters. Typically this is a unique number that the device's software can read such as a MAC address.Vendors can add individual serial numbers and add a range of numbers in addition to deleting numbers and getting specific information about each serial number including it's use status.Serial Numbers are key for the provisioning interface. Once a client model has been created, in order for any device to come online as that type of model, it must have two things happen. One is that the device client must be 'inserted' into the client hierarchy of the platform, creating an ownership link. The typical situation for this happens when a user adds a device to their web portal. The second thing is that a device must 'activate' with the Exosite platform as that type of device in which the platform will exchange a new CIK to the device. Manage ContentClient Models can have content posted. This content is accessible to all devices that have activated with a serial number and have a valid CIK. This content can be any 'blob' of information, most typically the content files are firmware files for in-field updates, configuration files, playlists, and media like images, videos, and audio files. Devices can check in for a list of content available to it with timestamps to determine if it should download any new content.Content usage is up to each vendor. It is very powerful for doing in-field updates of software on devices and is highly recommended for deploying software to fleets of devices.Content that is added is by default available to all devices of the client model type.Manage Content and Serial Number GroupsVendors can create groups of serial numbers and content to control access to sub-groups inside of a client model fleet. Groups can be modified, added, and deleted using the vendor management interface.Groups can be used for example to provide a way to allow some devices to get more advanced features.Manage Shared Client ModelsVendors can choose to share their client models to other vendors. Those vendors can then make the shared client models accessible to their users. Client Model Use CaseClient Models are at the heart of the provisioning interface. They allow developers to create a 'profile' for a product's feature that can be quickly duplicated, created/manufactured, provisioned and managed in the field. The key to unlocking this functionality is the creation of a 'Client Model' in the Exosite platform which is a"cloud profile" that describes your product it represents the physical parameters (both real-time and historical) of a device. Every time a new device is added to the system, it will be a clone from this Client Model profile. For example, if a device OEM has a simple temperature sensor device that is logging ambient temperature to the cloud, the Vendor could create a Client Model with the following configuration:

Vendor ID: My Company ID

Model Name: Awesome Remote Temperature Monitor

Model ID: mytempdevice01

Model Serial Number Template: 1234

Model Content: [Firmware File]

Model Data Sources: Temperature (float), Analog Value (int), Ping (int)

Model Data Retention: 1 Month

Model Event Rules: Over Temp (Temperature > 80 for N seconds)

Model Scripts: Convert Analog value to Temperature in degrees

Model Valid Serial Number List: 0001, 0002, 0003, 0004

After creating this Client Model, devices that both match a valid model serial number AND are authorized by the owner for provisioning (time-windowed) can take advantage of the provisioning interface features.

Portals Device Overview

Portals is a user interface that provides a mean to manage and visualize the devices ( One Platform clients ) sending data to the One Platform (server). If Exosite Portals is being used to view devices and device data, the device must be added into Portals before the physical device client can send data or receive data. Each device has a unique CIK (Client Interface Key) number that identifies it to the platform.

Portals provides one way to interact with devices. Developers can also use the Exosite API to not only read and write data but also to created and edit device clients.

One Platform Clients Overview

Managing Devices in Portals

The devices page shows a table of all devices registered for a specific portal. Besides allowing the user to click on a device to see the device configuration popup, there are a couple of columns to point out here.

Name

Device name, this is meta information

Alias

The alias for the client in the platform

Type

Either 'generic' or a client model created by a vendor

Unique ID

Only used by client models. Not used by generic device type.

Location

Another field put into meta information for the client.

client's meta field

Clicking on a device will open its pop-up box. This shows all of the specifics about the device setup, its list of data sources (alias). Deleting a device is also possible here. Clicking on a data source opens up another pop-up about Data Information where you can see the data log. To add a data source for a specific device, go to the Data page onnavigationmenu to get to the Data Sources page.

Adding a new device

Adding a new device is simple and starts by going to the Devices page, or on some custom (sub-domain) Portals, there may be a link on the default home page.

1. Click theAdd Devicebutton. (Shown with red arrow below)

2. ADevice Setuppopup window will guide you through the setup process. Select the appropriate device type, device timezone, and provide a descriptive location value. Click the Continue button to continue.

A note about device types. The device type provides for different protocols and custom devices that Exosites One Platform supports.

3. Give the device a name, verify the information from the previous step, and click Submit to complete the process. If you need to go back, click the Device Setup text link.4. You should see the new device added to the device table. You can now start using this device.

Details

One Platform Clients Overview

CIK

Client Interface Key. A secret unique identifier number for a device to the platform. The One Platform generates the CIK automatically when a device client is created. CIK's for a vendor client model type device can be re-generated. APIs that take action on behalf of a device including reading from and reading to it's dataports require the CIK.

Name

Arbitrary name provided to identify the device to a user. This is a 'friendly' name that can be specified.

Alias

An alias for this client in the One Platform. Optional to use but APIs, widgets and other functionality may require one. An Alias is a simple identifier for the client's RID (resource identifier).

Type

Exosite supports clients that are either 'generic' or that are of a specific Client Model, which must be created by a device OEM. More Information for Managing Client Models in Portals

Location

Arbitrary location provided to help identify device to user. Examples: Office, Factory, North Field, etc. This location settings is put by Portals into the client's meta field.

Timezone

The timezone for the given device. Important for recording time stamps and providing accurate time based values to the user. Should be specific to the location of the device, not the user. This timezone information is put by Portals into the and Portals uses it to show data in that timezone even though data is stored as UTC.

Portals includes a manage area for Platform scripts attached to clients. All scripts for each client device is listed at the sub-domain specific URL /manage/scripts. Clicking on a script will open the Portals script editor.

Platform Scripting Overview

The Script Manage Table

The script manager table allows users to add new scripts to attach to devices and at the Portal level or select an existing script to open the script editor. The status of the scripts is also shown (Waiting, Running, Completed, or Error).

The Script Editor

The script editor allows users to edit and delete scripts in the Exosite platform. Each script is attached to a client (usually a device or at a Portal level). The debug log shows a timestamp for each debug message from the script. The editor also shows the Status of the script, a Lua syntax editor window, and a list of available Aliases which are usually data sources and data rules.

As a convenience function, double clicking an alias from the list will automatically insert it into the script syntax editor at the top of the code. This saves users time from having to write out each alias as a local variable.

Domain Widgets use Portals Custom Widget engine to render JavaScript scripts configured by domain administrators to be used as normal widgets by users on the domain. When a Domain Widget is published on the domain, it will appear in the Add Widget wizard with an accompanying name and description. Domain Widgets are only available for domain administrators and whitelabel owners.

How they work

When a user adds a Domain Widget to their dashboard, the widget loads the Javascript code directly from the Portals domain widget database where the code is stored. The size, selected data sources and refresh rate are saved in the users dashboard configuration, and when the dashboard renders it combines the Domain Widget code and users configuration to display the widget.

Because the Domain Widget code is loaded directly from a central database, any updates that are made to the Domain Widget by the admins are automatically reflected on all widgets of that type throughout the domain. Unlike Custom Widgets, Domain Widgets will render the same way for the dashboard owner, portal managers, private viewers or public viewers. As it is added by the domain admin, it is considered safe and warning messages to anyone but the owner are disabled.

More information about how the Custom Widget works can be found on the Custom Widget documentation page.

Examples for Custom Widget scripts can be found on the Custom Widget Github page.

Setting up a Domain Widget

Domain Widgets can be created and managed on the Domain Widget page in the subdomain admin interface, found on the left menu under 'Domain Setup'.

There are three fields which can be configured when creating or editing a Domain Widget.

Name : Displays as the Widget Type when a user is creating a new widget or is viewing the widgets edit page. Required field.

Description : The Description when a user is creating a new widget. Optional.

Code : The Javascript code that will be run when a user views the domain widget.

After a Domain Widget has been created, it will need to be Published in order for a user to be able to select it from the add widget process on their dashboard. Domain Widgets that have already been added to a dashboard will continue to function properly if it has been Unpublished. If the Domain Widget has been deleted, the users widget will not work anymore.