Configure Data Channels

Requirements

To provision channels, you will need to:

be a member of an organization, and
have been granted a role with channel creation permissions.

For example, to provision channels, You will need to be a member of any role with the channel_create permission.

If you are the administrator of the organization, you will have all permissions already granted to you. Otherwise, if you have been invited to the organization, you can request from your administrator to grant you the appropriate role.

Provisioning

You can provision channels in bulk or one by one.

Provisioning a single channel

Head over to the channels page. Click on "Create channel." In the dialog that pops up, you will be prompted to provide the channel's information.

Create channel button.

Here are the details of each field:

Create channel dialog.

Field	Description	Example
Name	The display name of the channel.	"org/smartlight/SmartLight/data" or "My Channel"
Route	The channel's unique identifier. Can be used in place of the ID; and, similarly, cannot be changed after creation.	smart*light
Description	A description of the channel.	*"A channel used by smart lights and related devices"_
Tags	A comma-separated list of tags. Can be helpful when filtering and searching.	home, lighting, automation
Metadata	A JSON object that describes the channel. Note that the property `location` is reserved by Gridsense to allow maps to work properly.	{"room": "1F"}

Provisioning multiple channels (bulk provisioning)

Head over to the channels page. Click on "Bulk provision channels." In the dialog that pops up, you will be prompted to upload a file that contains the information of one more more channels. You can click to open the file selector or drag and drop the file directly. The file can be either JSON or CSV, and must conform to the schema of each file.

Bulk provision channels dialog.

JSON file schema

The JSON file must be an array of objects. Each object must follow the following schema:

Field	Description	Example
Name	The display name of the channel.	Smart Light
Tags	A JSON array of tags. Can be helpful when filtering and searching.	["home", "lighting", "automation"]
Metadata	A JSON object that describes the channel. Note that the property `location` is reserved by Gridsense to allow maps to work properly.	{"room": "1F"}

Example JSON file

[
  {
    "Name": "org/smartlight/SmartLight/data",
    "Tags": ["home", "temperature", "energy"],
    "Metadata": {
      "room": "1F"
    }
  },
  {
    "Name": "org/smartlock/SmartLock/alerts",
    "Tags": ["security", "home"]
  }
]

CSV file schema

The first row of the csv file must be the header. There are three columns:

Field	Description	Example
Name	The display name of the channel.	Smart Light
Tags	A JSON array of tags. Can be helpful when filtering and searching.	["home", "lighting", "automation"]
Metadata	A JSON object that describes the channel. Note that the property `location` is reserved by Gridsense to allow maps to work properly.	{"model":"SL2025", "warranty": "void"}

Make sure the headers are properly capitalized; e.g. you should write Name and not name.

Although only the Name field is required, the other column headers (Tags and Metadata) must be present, even if all rows leave them blank.

Example CSV file:

Name	Tags	Metadata
org/smartthermostat/SmartThermostat/data	["home","temperature","energy"]
org/securitycamera/SecurityCamera/alerts	["security","camera","home"]

Finish provisioning

Once you have imported the JSON/CSV file, you will see a preview of the first five channels. You can complete the provisioning step by clicking "Provision." If you are unsatisfied with the result or would like to make changes, you can click "Discard" to start over.

Bulk provision channels dialog with imported data.

Recommended approach

The recommended approach to channel creation is to create two channels; one for telemetry (continuous sensor readings, live data, etc.) and another for events (one-off events like object detection).

An example of the recommended approach

Once you have created the two channels, you can connect each device that you provision afterwards (or have already provisioned) to both of them. This allows you to share your messaging setup (e.g. MQTT scripts) across all your devices so you can think only about the messages and sensor readings themselves.

On this page