User guide

User guide for Yggio

Create an account in Yggio

How to create your account

  1. Open Yggio webpage (staging.yggio.net) in your browser

  2. Press the ”Create an account” button

  3. Enter a new username and password and check the Accept Terms and Policy box

  4. OPTIONAL: Select the visibility of your account, making your account visible or invisible for other users

  5. Press the "sign up" button to create your new account

Control Panel V2

control-panel-v2-devices

Adding devices to Yggio

How to connect a LoRa device (Single mode)

  1. Navigate to "Devices" from the menu bar at the top

  2. Click on "New device" then "Single mode"

  3. In the "Select device type..." drop down, choose LoRaWAN, then hit "Continue"

  4. In the next step you are prompted to select a connector which is a link to a LoRa Network Server such as Chirpstack, TTN, Netmore etc. Select the connector that applies to your device

  5. Once a connector has been chosen, a new drop down is introduced that allows you to select "Activation Type", "OTAA" or "ABP". Choose the type that applies to your device

  6. Fields to enter device keys are now visible as well as other required information. Which fields are required in your case depends on the LoRa Network Server application

  7. If you wish to decode your device's payload, select the mode name that is used for your device. This field can be left empty and changed later on

  8. In the next step you can add additional translators, once you're done, hit "Continue"

  9. The final step "Details" lets you set a name for your device, as well as a description. If you want to add your device to a specific Location (Location Manager), you can do so here. You can also add contextual parameters. When ready, click on "Add device"

  10. The last page "Result" will let you know if your device was added successfully or if problems were encountered

How to connect a LoRa device (Batch mode)

  1. Navigate to "Devices" from the menu bar at the top

  2. Click on "New device" then "Batch mode"

  3. Upload your csv batch file by dragging and dropping it onto the grey box or click on the grey box and select your file on your computer. If you need information on how to create a batch file, click on the link "What should I put in the file?"

  4. When the file has been uploaded, you will be notified if the file is valid or not. If the file is valid, press "Continue" to proceed

  5. In the next step, the amount of devices to be installed will be displayed, if the information is correct, click on "Start installation"

  6. After the installation has finished, information about the result is shown. In case of errors, download the errors file to troubleshoot. To exit the Batch installer, hit "Done"

Control Panel V1

control-panel

Navigate to Control panel

  1. Log in to your account

  2. After you have logged in you should be directed to the Control panel

Adding devices to Yggio

How to connect an ICPE Z-Wave gateway to Yggio:

  1. Login to Yggio with your username and password

  2. Navigate to IoT-nodes on the left side

  3. Press the New IoT-Node button in the top left corner

  4. Choose Z-Wave Gateway

  5. Enter the Z-Wave Gateway Mac-address (Provided on bottom of ICPE) and press next

  6. Give the Gateway a name and press Next

  7. On Manage access rights press Next

  8. On Overview press Save

  9. You should be able to see your device if you filter for Z-wave gateway or search for the name it was given

  10. Check if the gateway status is ”Gateway online”

How to include/exclude a Z-Wave device:

  1. Locate your newly added Gateway in the IoT-node tab with filtering by Z-wave gateway

  2. Press on your Gateway to open viewing popup window

  3. Navigate to Z-wave include/exclude tab

  4. Change mode to exclude with the crossing arrows

  5. Press ”Start exclude”

  6. Trigger the device for include/exclude

  7. Confirm that you get a message saying your device is successfully excluded

  8. Change mode to include with the crossing arrows

  9. Press ”Start include”

  10. Trigger the device for include/exclude

  11. Confirm that you get a message saying your device is successfully included

  12. Enter a name for the newly included device node

  13. Save the device and close the popup window

How to connect a LoRa device:

Yggio supports several different LoRa integrations. For every integration, there needs to be a Connector created so that each LoRa device added can be connected to respective integration. If you already have a Connector set up, you can skip to step 4 for every new LoRa device you wish to connect.

  1. Navigate to ”New IoT-node” on top left corner

  2. Select device type ”ChirpStack Connector”

  3. Fill in the necessary details provided by the chosen Lora integration

  4. Once the Connector has been created, repeat step 1 then skip to step 5

  5. Select device type ”LoRa”

  6. Select which Connector (integration) you want to use

  7. Select type “OTAA” or “ABP” as type, depending on your device

  8. Enter device ID (devEui)

  9. Enter Device Address (devAddr) (ONLY ABP)

  10. Enter Network Session Key (nwkSKey) (ONLY ABP)

  11. Enter Application Session Key (AppSKey) (ONLY ABP)

  12. Enter Application Key (appKey)

  13. Go to Step 2 (Details in tour guide) by clicking Next

  14. Enter a suitable name for your device

  15. Select correct model name (translator for your device)

  16. Go to Step 3 (Manage Access on tour guide) by clicking Next

  17. Go to Done step by clicking Next

  18. Click on Create button to save the LoRA device

  19. Find the device by filtering by “LoRa-node” or search for the given name

  20. Click on the device name to open device popup window

  21. Read the device manual for instructions on how to connect your device

  22. When you have connected your device, press the refresh button in the top right corner of the popup window

  23. Check the status of the device. Confirm that the device is reporting and is connected with a LoRa gateway. Please note that some devices can take a few minutes or more until they report data.

User groups

Navigate to User groups

  1. Log in to your account

  2. Click on ”User groups” on the left sidebar

Create a user group

  1. Press the “New” button on the top left corner

  2. Enter your group name in the box

  3. Press the “Add” button

Add users

  1. Press the “Manage” button in the top left corner

  2. Find the group you created in the filter box

  3. Select your group

  4. Enter an existing user in the “Add member to group” field box

  5. Press the “Add” button next to the field box

Access rights

Navigate to Access rights

  1. Log in to your account

  2. Click on ”Access rights” on the left sidebar

Give access rights to users and groups

  1. Enter a user or group name in the “Enter username or group name here” field box

  2. Press the “Select” button next to the field box

  3. Give out access rights for a specific device in the list by pressing on the “Read” and “Write” buttons on the right side next to the device names

  4. To give our access rights for many devices, press on the “All”, “Read” and “Write” buttons on the right side above the list

Location Manager

location-manager-1

Navigate to Location Manager

  1. Log in to your account

  2. Click on ”Apps” on the left sidebar

  3. Click on ”Location Manager” to go to the Location Manager

Create a Location

  1. In the Location Manager, press on the “New location” button on the left side

  2. Choose a name for your new Location

  3. Choose a description for your new Location

  4. Enter your coordinates or press on the map to select your Location

  5. Once all fields are green, hit the submit button in the bottom left

Add a Blueprint

  1. Go to a Location you created by either finding it on the map and clicking on it, or in the list on the left and click on the name or aim button and press the “go to location” button on the map

  2. When you are “inside” your new Location, press the “New Blueprint” button on the left side

  3. Choose a name for your new Blueprint

  4. Select and/or upload a Blueprint of your new Location

  5. Press the “Create Blueprint” button on the bottom left

Add a device (in Location Manager)

  1. Go to a Location you created by either finding it on the map and pressing on it, or in the list on the left and press on the name or aim button and “go to location” button on the map

  2. On a Blueprint, click on the “Arrow” button next to the “Pen” button

  3. Click on “Add device”, and a dropdown menu will appear

  4. Choose the device you want add to the Blueprint

  5. Press the “+” button on the Blueprint list

  6. On the “Crosshair” button on the map, a red label with your unplaced device should appear

  7. Press the “Crosshair” button and then click on the Blueprint to place the device at the same position as the mouse click

  8. Adjust the position of the device by dragging it to the desired spot

  9. Press on the “Crosshair” button again to go back to the Blueprint

Rule Engine

rule-engine

Navigate to Rule Engine

  1. Log in to your account

  2. Click on ”Apps” on the left sidebar

  3. Click on ”Rule Engine” to go to the rule engine

Create a Rule

rule-engine-create-rule

  1. Click on the ”Rules” icon in the Rule Engine

  2. Select ”Add Rule” on the middle left side

  3. Enter Rule name

  4. Choose a WHEN trigger. This function defines when something is being done. Enter your values and press on the ”+” button in the middle

  5. OPTIONAL: Choose an IF condition. This function will trigger an Action IF something happens. Enter your values and press the ”+” button in the middle

  6. Choose a DO Action. This function will do something once the WHEN and IF conditions are met. Enter your values and press the ”+” button in the middle

  7. Press on ”Add Rule” in the bottom left side

Create a Condition

rule-engine-create-condition

  1. Click on the ”Condition” icon in the Rule Engine

  2. Select ”Add Condition” on the middle left side

  3. Enter your Conditions Name

  4. Enter your Conditions value. This function will use the value entered as the trigger

  5. Press the ”Add Condition” button on the left side

Permitted operators: Permitted operators can be found here

Permitted data types: Integer, Decimal, Boolean, String

Examples:

value.statement === true && message === 'Missing expected report'
value.temperature < 39.5 || presence === false

Create an Action

  1. Click on the ”Action” icon in the Rule Engine

  2. Select ”Add Action” on the middle left side

  3. Enter your Actions name

  4. Choose what type of Action you need and select it

  5. Enter correct values for your Action

  6. Press the ”Add Action” button on the left side

Create a Contact

  1. Click on the ”Contacts” icon in the Rule Engine

  2. Press the “Add Contact” button

  3. Enter name, e-mail and phone number

  4. Press the “Add contact” button in the bottom left


Generic integration

Nodes which are not currently supported by Yggio can be made available through the generic integration.

Generic devices are identified by a globally unique id. There are a number of properties that can be chosen as the holder of you id.
Currently supported identifiers:

IdentifierName Description
id Fiware entity id
secret String between 8 and 128 characters, include only A-Z, 0-9, -, . and _
devEui 64-bit globally-unique Extended Unique Identifier (EUI-64)
gatewayEui 64-bit globally-unique Extended Unique Identifier (EUI-64)
imei International Mobile Equipment Identity, 15 digit number
tag any string
serialNumber any string

There are two actions that needs to be performed, in any order:

  1. Create the node through the control panel (or API, it follows Adding devices to Yggio)
    1.1 Login to Yggio with your username and password
    1.2 Navigate to IoT-nodes on the left side
    1.3 Press the New IoT-Node button in the top left corner
    1.4 Choose Generic
    1.5 Enter the unique id to be used for this device and press Next
    1.6 Give the node a name and press Next
    1.7 If everything looks OK, press Create, then Finish

  2. Send data to the integration, either by using HTTP or MQTT.
    For MQTT, see MQTT Broker.
    For HTTP, a message should be sent to <server>/http-push/generic with this format:

{
  <identifierName>: <identifier>,
  "basically": "any",
  "json": "compatible",
  "information": [1]
  "stuff": {
    "nested": "is allowed"
  }
}

The request must also include either a header or querystring that determine your identifier: identifier=<identifierName> An example:

curl -sS https://staging.yggio.net/http-push/generic?identifier=secret \
-H 'content-type: application/json' \
-d @- <<EOF
{
  "secret": "ABCDEFGHIJKL_1234567890",
  "basically": "any",
  "json": "compatible",
  "information": [1],
  "stuff": {
    "nested": "is allowed"
  }
}
EOF


Device Updater

1. Start by searching for the device you wish to update. Keep in mind that the search is case-sensitive, so include capital letters where necessary. The lower box will display any matching results and allow you to select your device from the list. Once you have selected your device, press 'Continue.'

device-updater-step-1

2. Next, you will be able to choose which parameters to update. You can select multiple parameters here. Click 'Continue' to proceed.

device-updater-step-2

3. You will now be prompted to edit all the parameters chosen in the previous step. After you have made your changes, click 'Continue' to proceed to the next parameter.

device-updater-step-3

4. Once all the steps have been completed, click "Update another device" or close the window.


Logs

In logs you will find a history of all events occurring in your account including device updates, alarms, access rights, edits, downlinks and more.

logs-1

Filters

To ease monitoring efforts, a filter is available. The following filters can be used:

Type

  • Error: Error conditions detected, e.g. system tried to execute a command but failed to get response in time or a device failed to report in time
  • Warning: Typically low signal strength or some other sensor related issue such as an intrusion detection. Severity of the warning can be deduced from the priority
  • Info: Basic log

Priority

  • Low: Notification: NO. Most log events that are low severity will use this.
  • Medium: Notification: NO. Any possible action can be delayed, nothing serious will happens even if no action is taken.
  • High: Notification: YES. Typically this will be a serious warning that requires fast actions.
  • Severe: Notification: YES. Something serious has happened that requires urgent attention (typically risk for fires, explosions, etc).

Category

  • Status: General e.g. alarms, state, external errors
  • Update: Update of a node
  • Command: Downlinks
  • Access: Access rights granted e.g. account x granted read access to user y
  • Analytics: Device updates when new data is reported
  • Rule: Rule Engine related events

Message

  • Input unrestricted text relevant to your search.


Alarms

Alarms fall under the 'Status' category and are consistently accompanied by a 'Verify' button. It is essential to understand that verifying an alarm is a prerequisite for its reactivation. Failing to meet this requirement may lead to overlooked alarms.

logs-2