flespi gateway show and tell: 10 minutes to see platform in action

Articles on our blog are as clear as possible. Every string in documentation is absolutely concise. All pages at our site are completely informative. At least I hope that’s just the way it is ;) But what if you don’t have enough time to explore all that stuff? What if interaction with the platform is not (impossible!) as clear as I thought? This post will tell you about flespi gateway in show-and-tell mode: simple steps, perceptible screenshots andfast result – nothing more.

Ok! Let’s assume that somehow you have found your path to flespi.io: from this site, by invitation letter, or using big red button down here. Anyway, the good thing to know is that flespi.com contains descriptive information, while gateway platform by itself is hosted under .io domain.

flespi.io meets you with login screen where you can use one of your social media accounts to authorize on gateway platform. After authorization you will find yourself on Personal account page where you can edit your account information and manage your authorization tokens. You can read about tokens in more details at API guidelines page. As for now you need to know that you’ve been provided a token allowing you to try flespi gateway in action: hit Documentation link on the top right corner.

flespi documentation is built with swagger framework. Thus, our documentation is interactive: it allows not only to review available REST API methods and its specifications, but also to construct any API request in UI mode, send it to the platform and view the result. Documentation page consists of the following structural parts:

Navigation tab to switch between entities.

Description field for the selected entity.

Available methods to manipulate entities.

Let’s construct and perform a request to flespi gateway. At first, we need to know what protocols are currently supported by the platform. Click “protocols” link on the navigation tab: there is only “GET” REST API call to be performed.

Click on the request frame to expand it and take a look at “Try it out!” button.

Note an exclamation mark on the right side of the button. By clicking on it you will be prompted to authorize the session with the platform:

This step is to be done only for the first request to the gateway during the current session. Now your requests are authorized and you can click on “Try it out!” button.

The result of the request appears in the lower section. There is also curl command line request that can be performed right from the terminal:

The core info for us here is that we are going to use test protocol with id=1 to create our very first channel to touch gateway features. As specified in protocol description:

Test protocol is used for demonstration and testing purposes.Connection to a channel with a given protocol allows to emulate interaction between a device and flespi gateway. Connect to the channel's IP:port via telnet-like tool with the following options available:1. set an ident (to emulate device-like interaction connection that can be identified with device's unique string).2. register messages(to emulate registration of up to 1K messages from the emulated device).3. switch to echo mode: connection will reply with received data to any incoming message.

So here is our plan:

Createa test channel. The channel will provide us host:port on flespi server.

The most valuable stuff for us here is that a new channel has started to listen for new connections on 193.193.165.37:20017.

2. Emulate connection to the channel created

connect to 193.193.165.37:20017 via telnet-like tool

enter 1 and set the emulating device identification string

enter 2 and register several messages

enter 3 to switch the channel into echo mode

The result of actions described above is that we have created a channel with a test protocol and registered 10 messages from the “device” with ident=12345678. Let’s check it with REST API calls.

3. Check the connection

go to Connections page using navigation tab

perform GET request to all channels for all connections

verify that the device with a given ident is currently connected

4. Get messages from the device

Go to the messages tab and expand GET request frame. You might notice the ch.selector frame just above data parameters.

This parameter is used to specify the channel being targeted with a given request. In our case we have only one channel (created on step 1), so we don’t need to change the default value. But keep in mind, that the request sent to all channels specified in {ch.selector}field may cause unexpected result. See API guidelines for more information about selectors in particular and about API requests in general.

Click “Try it out!” button to see all messages registered by the emulated device.

5. Send a command to the device

Before we send a command to the connected instance lets find out what commands are supported by the test protocol. Navigate to protocols/commands tab and perform GET request (don't forget to specify protocol ID in protocol-selector field, or “name=test” to avoid seeing commands from uninterested protocols).

The first command can be used to send properties of any type. The second one is an example of a specific command that can take only boolean “force” property and must have an integer “period” property (and the command will not be sent if verification is not passed). We are going to try to send query_pos command:

“Expires” parameter means a command lifetime. If a device with the specified ident is not connected to the channel specified by {ch.selector} the command will be stored in the commands queue until “expires” moment (UNIX timestamp). The command from the queue is sent to a device with the given ident as soon as the device connects to the channel and registers its ident. Commands (sent and expired) are pushed to the commands-result list and can be reviewed via GET /commands-result request.

Hint: the process of adding command parameter

Click on “Object properties” button. A drop-down area with a prompt to write property name will appear.

Fill in “property name” field and click on “Add” button.

An area to fill in the new field appears. Select the type of the new field.

Fill in “value” field of the new command parameter.

An added parameter is now stored in the object properties list. You can repeat the steps above to add other object parameters.

6. Close the connection

From the gateway’s side, test connection can be closed using DELETE /connections request.