Page tree
Skip to end of metadata
Go to start of metadata


Contents



What is a Virtual Network?


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

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

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

  • A gateway can be in several Virtual Networks simultaneously.

  • In the current implementation, only Server Operators 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 Organisation.

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

  • Any Organisation 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.

  • 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) With a Server Operator account, log in to the admin interface (https://example.loriot.io/adme) 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:

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.


 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:

/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)' \

Please be sure to use the Access Token for your Account, not a specific Application.


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:


{

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

}


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.

{"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

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


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

{"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”:

{"cmd":"mtxd","mcasteui":"FE0000000000002D","seqdn":84,"ts":1580819642295}
  • No labels