Creating Gateways

This page explains how to create, configure, and manage gateways

Creating or editing a gateway​

You can create a gateway or edit an existing one using console. After you create a gateway, you can't change it to a non-gateway device. Make sure you've created a registry and a device key pair before completing the steps in this section.

Console

To create a new gateway:

1. Go to the Registries page in console.

2. Click the ID of the registry for the gateway.

3. On the Registry details page, click Gateways, then click Add gateway to create a new gateway.

4. Enter a Gateway ID that briefly describes the gateway or otherwise helps you identify it. (This field can't be edited later.) For information on gateway naming and size requirements, see Permitted characters and size requirements.

5. For Gateway communication, select Allow or Block. This option allows you to block communication when needed, such as when a gateway or one or more devices bound to it are not functioning properly. In most cases, you'll want to allow communication when first creating the gateway. When a gateway is blocked, all devices bound to it are also blocked from communicating with OmniCore.

6. Select the Public key format that matches the key pair for this gateway. Paste the certificate or key in the Public key value field. You can also set an expiration date for the key.

7. Select the authentication method to use for devices bound to the gateway.

8. Use the Key and Value fields to add optional gateway metadata, such as a serial number. For information on metadata key-value naming and size requirements, see Permitted characters and size requirements.

9. Under Logging, select an activity log level for the gateway. The gateway's log level overrides its registry's log level.

10. Click Create to create the gateway or Update to save changes to an existing gateway.

To edit an existing gateway:

1. Go to the Registries page in console.

2. Click the ID of the registry for the gateway.

3. Click Registry details.

4. Click Gateways.

5. Click the ID of the gateway you want to edit.

6. Click Edit at the top of the page.

To add a key to an existing gateway, click Add public key on the Device details page.

Go

Use the following methods to create or edit a gateway:

• Device create method to add gateways to registries Create Gateway

• Device patch method to edit existing gateways Modify Gateway

// createGateway creates a new OmniCore gateway with a given id, public key, and auth method.
// gatewayAuthMethod can be one of: ASSOCIATION_ONLY, DEVICE_AUTH_TOKEN_ONLY, ASSOCIATION_AND_DEVICE_AUTH_TOKEN.

package
main

import (
    "bytes"
"fmt"
"io"
"log"
"net/http"
"os"
)

var BASEURL = "<BaseUrl>"
var subscription = "<subscriptionId>"
var registryId = "<registryId>"
var token = "Bearer <token>"
var url = fmt.Sprintf("%s/subscriptions/%s/registries/%s/devices", BASEURL, subscription, registryId)

func
main()
{

    var jsonData = []
    byte(` {"id": "gatewayId","gatewayConfig":{"gatewayType":"GATEWAY","gatewayAuthMethod":"ASSOCIATION_ONLY"},"credentials": [{"publicKey": {"format": "RSA_X509_PEM", "key":    "<PublicKeyBytes>"}}]}`)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header = http.Header
    {
        "Content-Type":
        {
            "application/json"
        },
        "Authorization":
        {
            token
        },
    }
    client := &http.Client
    {
    }
    res, e := client.Do(req)
    if e != nil {
        log.Fatal(e)
    }

    defer
    res.Body.Close()

    fmt.Println("response Status:", res.Status)
    fmt.Println("Created Gateway Device")
    // Print the body to the stdout
    io.Copy(os.Stdout, res.Body)
}

To learn how to create the devices you'll use with the gateway, see Creating or editing a device.

Configuring the gateway and getting state​

With OmniCore, you can control a gateway by modifying its configuration, just as you would with any other device. See Configuring Devices to learn how to configure a gateway over the MQTT or HTTP bridge.

After a configuration has been applied to a gateway, the gateway can report its state to OmniCore. You can compare the gateway's state and its most recent configuration to make sure the gateway is doing what it's supposed to be doing.

Binding or unbinding a device​

You can authenticate non-gateway devices to OmniCore by binding them to the gateway. Binding creates an association between the devices and the gateway that OmniCore checks to authenticate the devices.

NOTE

Binding is required when using the HTTP bridge.

Console

1. Go to the Registries page in console.

2. Click the ID of the registry for the gateway.

3. Click Gateways, then click the gateway's ID.

4. On the Gateway details page, click Bound devices.

5. Click Bind device.

6. Select the devices you want to bind to the gateway, then click Bind.

7. To unbind a device, select the device in the Gateway details page and click Unbind device, then click Unbind again to confirm.

Go

Use the following methods to bind a device to or unbind a device from a gateway:

• Registries BindDeviceToGateway method to bind devices to gateways Bind Device to Gateway

• Registries UnbindDeviceFromGateway method to unbind devices from gateways Unbind Device from Gateway

// Bind a device to or unbind a device from a gateway
// bindDeviceToGateway creates an association between an existing device and gateway.
package
main

import (
    "bytes"
"encoding/json"
"fmt"
"io"
"log"
"net/http"
"os"
)


var BASEURL = "<BASEURL>"
var subscription = "<subscriptionId>"
var registryId = "registry"
var token = "<Bearer Token>"
var url = fmt.Sprintf("%s/subscriptions/%s/registries/%s/bindDeviceToGateway", BASEURL, subscription, registryId)


func
main()
{
    var jsonData = []
    byte(` {"deviceId": "deviceId","gatewayId":"gatewayId"}`)

    req, _
:
    = http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header = http.Header
    {
        "Content-Type"
    :
        {
            "application/json"
        }
    ,
        "Authorization"
    :
        {
            token
        }
    ,
    }
    client :=
&
    http.Client
    {
    }
    res, e
:
    = client.Do(req)
    if e != nil {
        log.Fatal(e)
    }

    defer
    res.Body.Close()

    fmt.Println("response Status:", res.Status)

    // Print the body to the stdout
    io.Copy(os.Stdout, res.Body)
}

Listing all devices bound to a gateway

Console

1. Go to the Registries page in console.

2. Click the ID of the registry for the gateway.

3. Click Gateways, then click the gateway's ID.

4. On the Gateway details page, click Bound devices.

Go

Use the following method to list all associations between a gateway and its devices: List All Bound Devices

Listing all devices bound to a gateway

// listDevicesForGateway lists the devices that are bound to a gateway.
package
main

import (
    "fmt"
"io/ioutil"
"log"
"net/http"
)
var BASEURL = "<BASEURL>"
var subscription = "<subscriptionId>"
var registryId = "registryId"
var gatewayId = "gatewayId"
var token = "Bearer <Token>"

var url = fmt.Sprintf("%s/subscriptions/%s/registries/%s/devices?gatewayListOptions.associationsGatewayId=%s", BASEURL, subscription, registryId, gatewayId)

func
main()
{
    client := http.Client
    {
    }
    req, err
:
    = http.NewRequest("GET", url, nil)
    if err != nil {
        //Handle Error
    }

    req.Header = http.Header
    {
        "Authorization"
    :
        {
            token
        }
    ,
    }

    res, err
:
    = client.Do(req)
    //We Read the response body on the line below.
    body, err
:
    = ioutil.ReadAll(res.Body)
    if err != nil {
        log.Fatalln(err)
    }
    //Convert the body to type string
    sb := string(body)
    log.Printf(sb)
}

Listing all gateways in a registry

Console

1. Go to the Registries page in console.

2. Click the ID of the registry for the gateway.

3. On the Registry details page, click Gateways to see a list of all gateways in that registry.

Go

Use the Gateway list method to list all gateways in a registry. List All Gateway Devices

Listing all gateways in a registry

// listGateways lists all the gateways in a specific registry.
package
main

import (
    "fmt"
"io/ioutil"
"log"
"net/http"
)
var BASEURL = "<BASEURL>"
var subscription = "<subscriptionId>"
var registryId = "registryId"
var token = "Bearer <Token>"

var url = fmt.Sprintf("%s/subscriptions/%s/registries/%s/devices?gatewayListOptions.gatewayType=GATEWAY", BASEURL, subscription, registryId)

func
main()
{
    client := http.Client
    {
    }
    req, err
:
    = http.NewRequest("GET", url, nil)
    if err != nil {
        //Handle Error
    }

    req.Header = http.Header
    {
        "Authorization"
    :
        {
            token
        }
    ,
    }

    res, err
:
    = client.Do(req)
    //We Read the response body on the line below.
    body, err
:
    = ioutil.ReadAll(res.Body)
    if err != nil {
        log.Fatalln(err)
    }
    //Convert the body to type string
    sb := string(body)
    log.Printf(sb)
}

Deleting devices bound to a gateway​

To delete a device bound to a gateway, you first unbind the device from all gateways it's bound to, then delete the device from the registry. Delete a Device

Console

1. Unbind the device from every gateway it's bound to.

2. In the Device details page, click Delete.

3. Enter the device ID to confirm and click Delete.

Go

After unbinding the device from all gateways it's bound to, use the Device delete method to delete the device.

// deleteDevice deletes a device from a registry.
package
main


import (
    "fmt"
"io/ioutil"
"net/http"
)

var BASEURL = "<BASEURL>"
var subscription = "<subscriptionId>"
var registryId = "registryId"
var deviceId = "deviceId"
var token = "<Bearer Token>"

var url = fmt.Sprintf("%s/subscriptions/%s/registries/%s/devices/%s", BASEURL, subscription, registryId, deviceId)

func
main()
{
    client := http.Client
    {
    }
    req, err
:
    = http.NewRequest("DELETE", url, nil)
    if err != nil {
        //Handle Error
    }

    req.Header = http.Header
    {
        "Authorization"
    :
        {
            "Bearer Token"
        }
    ,
    }

    res, err
:
    = client.Do(req)
    //We Read the response body on the line below.

    respBody, err
:
    = ioutil.ReadAll(res.Body)
    if err != nil {
        fmt.Println(err)
        return
    }

    // Display Results
    fmt.Println("response Status : ", res.Status)
    fmt.Println("response Headers : ", res.Header)
    fmt.Println("response Body : ", string(respBody))
}

Deleting a gateway

To delete a gateway, you first unbind its devices then delete the gateway from the registry. Delete a Gateway

Console

1. Unbind all devices from the gateway.

2. Go back to the Gateway details page and click Delete.

3. Enter the gateway's name to confirm, then click Delete.

Go

After unbinding all devices from the gateway, use the Gateway delete method to delete the gateway, specifying the ID of the gateway you want to delete.

// deleteGateway deletes a gateway from a registry.

package
main


import (
    "fmt"
"io/ioutil"
"net/http"
)

var BASEURL = "<BASEURL>"
var subscription = "<subscriptionId>"
var registryId = "registryId"
var gatewayId = "gatewayId"
var token = "<Bearer Token>"

var url = fmt.Sprintf("%s/subscriptions/%s/registries/%s/devices/%s", BASEURL, subscription, registryId, gatewayId)

func
main()
{
    client := http.Client
    {
    }
    req, err
:
    = http.NewRequest("DELETE", url, nil)
    if err != nil {
        //Handle Error
    }

    req.Header = http.Header
    {
        "Authorization"
    :
        {
            "Bearer Token"
        }
    ,
    }

    res, err
:
    = client.Do(req)
    //We Read the response body on the line below.

    respBody, err
:
    = ioutil.ReadAll(res.Body)
    if err != nil {
        fmt.Println(err)
        return
    }

    // Display Results
    fmt.Println("response Status : ", res.Status)
    fmt.Println("response Headers : ", res.Header)
    fmt.Println("response Body : ", string(respBody))
}