documentation
HOME » DOCUMENTATION » TECHNICAL DOCUMENTS » The Semtech Network Server User Guide » Register and Connect Your Gateway to the Semtech Network Server

Register and Connect Your Gateway to the Semtech Network Server

This section explains how to configure your gateway to communicate with the Semtech Network Server. These steps should be repeated for each of the gateways you wish to connect to the Semtech Network Server.

Add Your Gateway to the Semtech Network Server

  1. Log in to the Semtech Network Server website if you haven’t already done so.

  2. Click Gateways in the menu on the left.

    /uploads/documents/images/NS02B0310-01-gateways.png

    Figure 1: Gateways Item in Left Menu

  3. Click Add Gateway.

    /uploads/documents/images/NS02B0310-02-add-gateway.png

    Figure 2: Add Gateway Button

    Note

    If prompted, and if you are comfortable doing so, allow the browser to access your location. The location is used to configure the location of the gateway. You can also configure it yourself as shown in the next step.

  4. Complete the form that appears:

    • Name:

      A human-readable name for the gateway. Only letters, numbers and dashes are allowed, e.g., gateway-one.

    • Description:

      A human-readable description, e.g., Gateway for testing.

    • Gateway ID (EUI64):

      Paste in the GATEWAY_ID you found earlier in the step: Find the Gateway ID.

      Note

      If you do not have the GATEWAY_ID, log back into your gateway and open the gateway configuration screen to discover it.

    • Location:

      If your gateway has a GNSS module, the gateway sets the location automatically.

      If your gateway does not have a GNSS module, set the location of the gateway by clicking + and - to adjust the zoom level and drag the pin on the map to the correct location.

    /uploads/documents/images/NS02B0310-03-gateway-form.png

    Figure 3: Gateway Creation Form

  5. Scroll to the bottom of the page and click the Submit button.

  6. The gateway page now appears, showing the status of the gateway.

Generate Client Certificates

  1. Log into the Semtech Network Server if you haven’t already done so.

  2. Click Gateways in the menu on the left.

  3. Click on the gateway you just created.

    /uploads/documents/images/NS02B0311-01-choose-gateway.png

    Figure 4: Select Your Gateway

  4. Click on the TLS certificate tab, then click Generate certificate.

    /uploads/documents/images/NS02B0311-generate-cert.png

    Figure 5: TLS certificate Tab and Generate certificate Button

  5. Four fields display:

    • Expiration date

    • CA certificate

    • TLS certificate

    • TLS key

    Following the instructions below, copy the fields. When copying each field, click in the field, press CTRL+A to select all, then CTRL+C to copy.

    1. Copy the contents of the CA certificate field, as shown in Figure 6, and save it temporarily in a text file. We refer to this in the next section as the CA_CERTIFICATE.

      /uploads/documents/images/NS02B0311-03-ca-cert.png

      Figure 6: Contents of the CA certificate Field

      Note

      Be sure to include the ---BEGIN CERTIFICATE--- and ---END CERTIFICATE--- lines when copying the CA certificate.

    2. Copy the contents of the TLS certificate field and save it temporarily in a text file. We refer to this in the next section as the TLS_CERTIFICATE.

      Note

      Be sure to include the ---BEGIN CERTIFICATE--- and ---END CERTIFICATE--- lines when copying the TLS certificate.

    3. Copy the contents of the TLS key field and save it temporarily in a text file. We refer to this in the next section as the TLS_KEY.

      Note

      Be sure to include the ---BEGIN PRIVATE KEY--- and ---END PRIVATE KEY--- lines when copying the TLS key.

Warning

When the certificate expires, the connection between the gateway and the network server will stop working. Write down the date indicated in the Expiration date field.

Before this date, you must repeat this step and generate a new certificate, and then add that new certificate to your gateway, as shown in the Add Your Gateway to the Semtech Network Server section.

Configure Your Gateway

In this section you configure your gateway with the Semtech Network Server settings and the certificates you just generated. The instructions for this vary depending on whether your gateway is running LoRa Basics™ Station, Semtech UDP Packet Forwarder with the ChirpStack Gateway Bridge, or ChirpStack Gateway OS. Follow the instructions below for your implementation.

Configure a Gateway Running LoRa Basics Station

Consult the gateway documentation to find out how you can set the credentials on your gateway. You need to find out where these files should be stored, the configuration path.

Note

If you can connect to your gateway using SSH or PuTTY, the configuration path will be the same folder that holds your station.conf file. Be aware that, if you search for station.conf, you may find multiple instances of the file within subfolders inside the examples folder. There should also be a station.conf file outside of this folder; the path containing this station.conf file is the one to use.

Create the following files at the configuration path (e.g., if the configuration path is /home, you would create the files in the /home folder):

  • tc.uri - set this file to the single line as shown below, replacing BASICS_STATION_ENDPOINT with the Basics Station Endpoint listed for your Frequency in the Regional Support section of the Semtech Network Server webpage:

     

    wss://BASICS_STATION_ENDPOINT

    For example, for the region EU868, where BASICS_STATION_ENDPOINT is eu868.basicstation.loracloud.com:443, the contents of the file is set to:

     

    wss://eu868.basicstation.loracloud.com:443

  • tc.trust - set this file to the contents of the CA certificate field in the network server gateway certificate section, saved in the previous step as CA_CERTIFICATE.
  • tc.crt - set this file to the contents of the TLS certificate field in the network server gateway certificate section, saved in the previous step as TLS_CERTIFICATE.
  • tc.key - set this file to the contents of the TLS key field in the network server gateway certificate section, saved in the previous step as TLS_KEY.

Configure a Gateway with the Semtech UDP Packet Forwarder

When working with the Semtech UDP packet forwarder, you need to first configure the ChirpStack Gateway Bridge.

  1. Locate the device running ChirpStack Gateway Bridge. This could be your gateway, a second device running Debian or Ubuntu on your network, or it could be a cloud server, as described in the Gateway section.
  2. You need to know the Gateway Bridge configuration path. If you installed ChirpStack Gateway Bridge yourself, you should already know the path. If you bought a gateway with ChirpStack Gateway Bridge installed, consult the documentation. We refer to this path as GATEWAY_BRIDGE_CONFIGURATION_PATH.

    Note

    If you can connect to the device running ChirpStack Gateway Bridge using SSH or PuTTY, the configuration path will be the same as the folder that holds your chirpstack-gateway-bridge.toml file. On some gateway models, the configuration path could be one of the following:

    • /etc/chirpstack-gateway-bridge
    • $HOME/.config/chirpstack-gateway-bridge
  3. Create a file at the GATEWAY_BRIDGE_CONFIGURATION_PATH named ca.pem, and populate it with the contents of the CA certificate field in the Network Server Gateways page CERTIFICATE tab, saved in the previous step as CA_CERTIFICATE.

    For example, if the GATEWAY_BRIDGE_CONFIGURATION_PATH is /etc/chirpstack-gateway-bridge the file will be saved at /etc/chirpstack-gateway-bridge/ca.pem.

  4. Create a file at the GATEWAY_BRIDGE_CONFIGURATION_PATH named cert.pem, and populate it with the contents of the TLS certificate field in the Network Server Gateways page CERTIFICATE tab, saved in the previous step as TLS_CERTIFICATE.

    For example, if the GATEWAY_BRIDGE_CONFIGURATION_PATH is /etc/chirpstack-gateway-bridge the file will be saved at /etc/chirpstack-gateway-bridge/cert.pem.

  5. Create a file at the GATEWAY_BRIDGE_CONFIGURATION_PATH named key.pem, populating this file with the contents of the TLS key field in the Network Server Gateways page CERTIFICATE tab, saved in the previous step as TLS_KEY.

    For example, if the GATEWAY_BRIDGE_CONFIGURATION_PATH is /etc/chirpstack-gateway-bridge the file will be saved at /etc/chirpstack-gateway-bridge/key.pem.

  6. Open the chirpstack-gateway-bridge.toml file at the GATEWAY_BRIDGE_CONFIGURATION_PATH. Find the section starting with [integration.mqtt.auth]. Make sure the type is set to generic, as shown in the code example:

     

    [integration.mqtt.auth]

    type=generic

  7. Locate the section in the chirpstack-gateway-bridge.toml which starts with [integration.mqtt.auth.generic]. Update or insert the following settings under the [integration.mqtt.auth.generic] section heading.

    • servers:

      Update or create the servers setting as shown below:

      servers=[ssl://mqtt.loracloud.com:8883]


    • ca_cert, tls_cert and tls_key:

      Update the ca_cert, tls_cert and tls_key settings as shown, where GATEWAY_BRIDGE_CONFIGURATION_PATH is replaced with the actual path to the gateway bridge configuration.

       

      ca_cert=[GATEWAY_BRIDGE_CONFIGURATION_PATH/ca.pem]

      tls_cert=[GATEWAY_BRIDGE_CONFIGURATION_PATH/cert.pem]

      tls_key=[GATEWAY_BRIDGE_CONFIGURATION_PATH/key.pem]

      For example, if your GATEWAY_BRIDGE_CONFIGURATION_PATH is /etc/chirpstack-gateway-bridge then this would be:

       

      ca_cert=[/etc/chirpstack-gateway-bridge/ca.pem]

      tls_cert=[/etc/chirpstack-gateway-bridge/cert.pem]

      tls_key=[/etc/chirpstack-gateway-bridge/key.pem]

  8. Update or create the event_topic_template, state_topic_template and command_topic_template as shown below, replacing TOPIC_PREFIX with the MQTT topic prefix listed for your Frequency in the Regional Support section of the Semtech Network Server webpage.

    event_topic_template=TOPIC_PREFIX/gateway/{{ .GatewayID }}/event/{{ .EventType }}

state_topic_template=TOPIC_PREFIX/gateway/{{ .GatewayID }}/state/{{ .StateType }}

command_topic_template=TOPIC_PREFIX/gateway/{{ .GatewayID }}/command/#

For example, for the region EU868, where TOPIC_PREFIX is eu868, these settings are:

event_topic_template=eu868/gateway/{{ .GatewayID }}/event/{{ .EventType }}

state_topic_template=eu868/gateway/{{ .GatewayID }}/state/{{ .StateType }}

command_topic_template=eu868/gateway/{{ .GatewayID }}/command/#


Make sure your chirpstack-gateway-bridge.toml file has the [integration.mqtt], [integration.mqtt.auth] and [integration.mqtt.auth.generic] sections with the server, ca_cert, tls_cert and tls_key fields under the [integration.mqtt.auth.generic] section as shown.

[integration.mqtt]

event_topic_template=eu868/gateway/{{ .GatewayID }}/event/{{ .EventType }}

state_topic_template=eu868/gateway/{{ .GatewayID }}/state/{{ .StateType }}

command_topic_template=eu868/gateway/{{ .GatewayID }}/command/#

[integration.mqtt.auth]
type=generic

[integration.mqtt.auth.generic]
server=ssl://mqtt.loracloud.com:8883

username=

password=

ca_cert=/etc/chirpstack-gateway-bridge/ca.pem

tls_cert=/etc/chirpstack-gateway-bridge/cert.pem

tls_key=/etc/chirpstack-gateway-bridge/key.pem

 

Configure a Gateway Running ChirpStack Gateway OS

ChirpStack Gateway OS is an open-source Linux based embedded OS that runs on Raspberry Pi based gateways and supports a range of shields. You can connect your gateway to the Semtech Network Server using ChirpStack Gateway OS. Download the chirpstack-gateway-os-base image from the ChirpStack Gateway OS Downloads page. Follow the steps in the section Option 1: Install the ChirpStack Gateway OS of our LR1110 hands-on-lab if you need assistance installing ChirpStack Gateway OS on your Raspberry Pi.

  1. If you are not already connected, log into the Raspberry Pi via SSH or PuTTY with the username admin and the password admin.

    $ ssh admin@RASPBERRY_PI_IP_ADDRESS
      admin
      
  2. At the command prompt, enter:

    $ sudo gateway-config
      
  3. At the password prompt, enter:

    admin
      
  4. When the configuration menu appears, select Edit ChirpStack MQTT Forwarder config, and click Enter.

    /uploads/documents/images/MQTT Forwarder config.png

    Figure 7: Edit ChirpStack MQTT Forwarder config option

  5. At the Edit ChirpStack MQTT Forwarder Config menu, select MQTT connection wizard, and click Enter.

  6. Enter the text shown below for the MQTT broker address screen:

    ssl://mqtt.loracloud.com:8883

    Press Enter to save.

  7. When asked if you would like to configure a CA certificate, press Enter to select Yes, then press Enter to select OK at the next prompt to open the nano editor.

  1. Copy the CA_CERTIFICATE you saved in the Generate Client Certificates section.

  1. Paste the contents of CA_CERTIFICATE into the nano editor using CTRL+V. (If you are using Windows, simply right-click).

    /uploads/documents/images/NS02B0312-02-CA-cert.png

    Figure 8: Nano Editor with Pasted CA_CERTIFICATE

  2. Save and close the file by pressing CTRL+O and then Enter to accept the filename and location as /etc/chirpstack-mqtt-forwarder/ca.pem. Press CTRL+X to exit.

  3. When asked if you would like to configure a client certificate, press Enter to select Yes, then press Enter to select OK at the next prompt.

  4. Copy the TLS_CERTIFICATE you saved earlier.

  5. Paste the contents of TLS_CERTIFICATE into the nano editor using CTRL+V. (If you are using Windows, simply right-click).

  6. Save and close the file by pressing CTRL+O and then Enter to accept the filename and location as /etc/chirpstack-mqtt-forwarder/cert.pem. Press CTRL+X to exit.

  7. Press Enter to select OK at the next prompt.

  8. Copy the TLS_KEY you saved earlier.

  9. Paste the contents of TLS_KEY into the window using CTRL+V. (If you are using Windows, simply right-click).

    /uploads/documents/images/NS02B0312-02-TLS-key.png

    Figure 9: Nano Editor with Pasted TLS_KEY

  10. Save and close the file by pressing CTRL+O and then Enter to accept the filename and location as /etc/chirpstack-mqtt-forwarder/key.pem. Press CTRL+X to exit.

  11. The Restart ChirpStack MQTT Forwarder screen displays. Press Enter to select OK.

  12. The gateway config menu displays. Select Quit and press Enter to exit.