Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Contents


Table of Contents
excludeContents
stylecircle


What is a Virtual Network?


➜ A Virtual Network is a collection of Gateways that allows Multicast downlinks to be sent to via a specific subsection of Gateways.

            ➜ A typical use case for a Virtual Network can be to turn on/off multicast devices only using gateways in a specific area of a city instead of throughout every gateway across the whole network.

            ➜ Only Gateways with GPS-synced clock must can be used, for otherwise, the required accuracy of the timestamps cannot be guaranteed otherwise and the Multicast downlinks will fail.

            ➜ Each gateway ➜ A gateway can be in several Virtual Networks simultaneously.

            ➜ In the current implementation, only Server Operators and the Server Admin will be able to create Virtual Networks for security and privacy reasons.

            ➜ At a later stage, the ability to create a Virtual Network will be extended to the Organisation Administrators, however, they will only be allowed to share the Virtual Networks with their own Organisation.

            ➜ Once a Virtual Network has been created and shared with an Organisation, it's the Organisation Administrator's responsibility to decide which Organisation Members accounts should be granted access to itthe Virtual Network.

            ➜ Any Organisation user Admin or User can send Multicast Downlinks as long as they have Multicast Devices and access to a Virtual Network.

            ➜ When sending Multicast Downlinks, it is mandatory to select a Virtual Network before being able to send the downlink.

            ➜ For the time being, Multicast functionality and Virtual Networks will only be available on private servers and will be extended to the Professional Public Servers at a later date.


Creating a Virtual Network


➜ At its core, the main function of Virtual Networks is to grant access to already registered and working gateways.

 Thus, the creation of a Virtual Network must be handled through the administrator interface like all other administrative functionalities.


a) Log in to the Server Operator interface and select the Virtual Networks category in the sidebar:

b) Now select the option Create new:


➜ A new menu will appear where you can enter the basic details, select the gateways you want to add to the Virtual Network, and finally select the Organizations with which you want to share it.


✔ In the Basic Details you can give the Virtual Network a specific name and a short description:


c) In order to select a gateway, you can either scroll through the available gateways or make use of the available filters and search mask:


d) Once you have found the gateway you want to add, simply left click on it to select it; the gateway will be highlighted in a light grey hue. Multiple gateways can be selected this way at the same time:


e) Finally, select which Organizations will have access to this Virtual Network by left clicking on the name of the Organizations; once selected they will be highlighted in a light grey hue.

➜ You can scroll through the menu or use the search mask to narrow the search. Multiple Organizations can be selected at the same time:


✔ To finalize the process, simply click on the Create Virtual Network button at the bottom of the page.


Sharing a Virtual Network with Users


 Once a Virtual Network has been shared with an Organization, all Organization Administrators and Server Operators therein can grant access to its user.


a) To achieve this, the Organization Administrator simply has to access the Virtual Networks menu from the Organisation Admin administrator interface:


➜ By clicking on Virtual Network’s name, you can see the details, manage the users, edit it or remove it the Virtual Network.

b) To manage which users from your Organization can access the Virtual Network, click on the button Manage users:


c) This opens the option to select which users can access the Virtual Network by clicking on them:


d) Afterwards, click on the Accept button at the bottom of the page to grant access to these users:

✔  These users will now be able to send Multicast downlinks through this Virtual Network.



➜ Multicast downlinks can be sent via two methods:

 The WebSocket sample application within the User Interface.

✔ Downlinks via API through the WebSocket


The WebSocket sample application within the User Interface


 a)Select the Application containing the Multicast Device: 


b) Enroll a Multicast Device:


c) Select the WebSocket sample Application: 


d) Select “Send data To Multicast Device” Configure the downlink parameters:

Note
If the date is too old, then an error will appear. 


Downlinks via API through the WebSocket 


➜ Our downlinks via API are done through WebSocket, not quite the same as the regular RESTful API calls.


Info
 If a multicast device has not been added through the User Interface, please use the documentation in the User API [5.7] page to create a new multicast device 


➜ We now need to get the ID for the the Virtual Network we will use:

Code Block
languagetext
/1/nwk/virtual-networks/shared-with-me -  List of virtual networks that the user is authorized to use

 
curl -X GET
"https://yourserver.url/1/nwk/virtual-networks/shared-with-me" -H "accept: application/json" -H 'Authorization: Bearer (APIKEY)' \


Tip
Please Keep note of the id, this will be used to select the correct VN for downlinks


➜ In order to send valid Multicast Downlinks the messages must follow the structure below:


Code Block
languagetext
{

cmd      : 'mtx';  // must always have the value 'mtx'

mcasteui :string;  // multicast EUI, 16 hex digits (without dashes)


virtualNetworks : array; // a number array containing the Virtual Network ID(s) separated by commas, e.g. [12,85]

port     : number;  // port to be used (1..223)

preload  : number; // pre-load time (milliseconds, optional)

fopts    : string; // LoRaWAN® frame header options / MAC commands (hex string)

date     : string; // UTC time of multicast delivery (timestamp, ISO String)

data     : string; // data payload (to be encrypted by our server)


                   // if no APPSKEY is assigned to device, error will be returned

}



Info
If you are unsure how to post downlinks to an application, you can find some in Example Downlink Messages



Additional notes


Multicast downlink confirmation

In this example, FE0000000000002D is the multicast device ID.


➜ Please note that the date should always be greater than the current time so this downlink can be sent at the given time.

Code Block
languagetext
{"cmd":"mtx","port":100,"mcasteui":"FE0000000000002D","userid":12,"virtualNetworks":[85],"data":"ff","date":"2020-02-04T09:09:00Z"}

 

➜ If the message is accepted and stored for later sending, the NS response will have mcasteui, mcastdnqid and cmd

Code Block
languagetext
{"mcasteui":"FE0000000000002D","mcastdnqid":"5e3960a8ff6ebb670d3925d9","cmd":"mtx"}


➜ If the date is too old then an error appears: (further errors might appear due to other validations)

Code Block
languagetext
{"cmd":"mtx","port":100,"mcasteui":"FE0000000000002D","userid":12,"virtualNetworks":[85],"data":"ff","date":"2020-02-04T12:10:00Z","error":"Invalid old date by 0.11 hours"}



➜ When the given date comes, the stored multicast downlink is executed. The network server then displays a message with “cmd”:”mtxd” and a parameter “seqdn”:

Code Block
languagetext
{"cmd":"mtxd","mcasteui":"FE0000000000002D","seqdn":84,"ts":1580819642295}