Connecting LoRaWAN Gateways

Contents

Overview

Firefly typically connects gateways through the Semtech UDP packet forwarder — the widely used path that most gateways support — or through the newer Basic Station packet forwarder over a WebSocket connection to the network server.

The sections below cover connecting to Firefly and day-to-day operation — Basic Station including registration and authentication; with Semtech UDP, a gateway record in Firefly is usually not required. Also: suspicious downlinks or timing, and monitoring in niotix under IoT Data Hub → Gateway Mgmt. Before you start, clarify the gateway protocol (UDP or Basic Station), region or frequency plan, the Firefly organization context, and — if niotix provides the integration — a valid API key (see Firefly connector).

Access & Navigation

The most important areas are:

  • in Firefly: Organization → Gateways
  • in niotix: IoT Data Hub → Gateway Mgmt (see Gateway management in that page)

Semtech UDP vs. Basic Station

Semtech UDP Packet Forwarder

Gateways using the classic Semtech UDP packet forwarder do not need to be pre-registered in Firefly. Firefly handles incoming packets directly through the UDP entry point.

Typical properties:

  • connectionless over UDP
  • no mandatory Firefly gateway record for pure radio connectivity
  • downlink timing relies more on JIT or RX-window logic

Basic Station

Basic Station is handled as its own connection type in Firefly and requires a gateway record to be created there.

Typical properties:

Creating a gateway entry in Firefly is required for Basic Station gateways. This is not required for gateways using the classic Semtech UDP packet forwarder.

What must be configured for Basic Station

For Basic Station, the following information and conditions are usually important:

  • WebSocket URL of the network server (tc.uri)
    typically wss://... and depending on the respective Firefly environment; for the public fireflyiot.com instance (Europe, EU868) a common endpoint is e.g. wss://ns.fireflyiot.com (WebSockets on 443)
  • Gateway EUI
    the 64-bit identifier of the LoRaWAN gateway, usually as 16 hexadecimal characters (8 bytes / EUI-64); must match exactly the value stored in Firefly for this gateway. Basic Station calls this the Station identity; in LoRa Basics™ Station it is set among other things via station_conf.routerid or derived e.g. from MAC and euiprefix, see Station Identity. Typically taken from the gateway hardware (e.g. MAC → EUI) and must be unique in the respective environment
  • Auth token
    Firefly validates the gateway using the EUI and the Authorization header
  • CA certificate / trust chain
    required if the gateway checks the LNS server identity during the WSS (TLS) handshake: typically a PEM-encoded root or intermediate certificate (issuer chain of the LNS server certificate), not a gateway client certificate. For fireflyiot.com (public SaaS, typically Let’s Encrypt), e.g. ISRG Root X1 (cross-signed, PEM) is common if a fully up-to-date system trust store is not used. For a custom hostname, internal CA, or on‑prem Firefly, configure the appropriate CA or issuer chain; for further details see also LoRa Basics™ Station (configuration) and the respective gateway handbook.
  • stable UTC time / NTP / GPS

In practice, this means:

  • create the gateway in Firefly
  • keep EUI and auth token consistent between Firefly and the gateway
  • use the correct wss:// URL of the Firefly instance
  • make sure NTP and, where available, GPS work correctly

What must be configured for the UDP Packet Forwarder

For the classic Semtech UDP Packet Forwarder, the main points are:

  • network server address
    depends on the Firefly environment; for the public fireflyiot.com instance (Europe, EU868) the typical LNS hostname is e.g. fireflyiot.com (details and other regions: Frequency plans and network server addresses)
  • UDP port of the network server
    typically 1700
  • matching frequency plan / region
  • correct UTC time source

Compared to Basic Station:

  • no pre-created Firefly gateway object is required for pure radio connectivity
  • no token-based Basic Station authentication is used
  • timing information is typically derived from tmms or time

The correct URL and port depend on the target environment. Self-hosted Firefly deployments use different hostnames than the public SaaS. The standard ports above are defaults for orientation and may differ depending on the environment.

Firewall and Port Checklist

This list summarizes IP-side requirements at the gateway (backhaul to the network server). For the full path end device ↔ radio ↔ gateway ↔ Firefly, see Architecture.

Semtech UDP Packet Forwarder

  • Allow outbound UDP from the gateway to the configured LNS host; destination port as defined for the environment (often 1700, see above).
  • DNS or a fixed destination IP must be reachable from the gateway.
  • NAT is usually sufficient when the gateway initiates the UDP flow; very short UDP timeouts or strict stateful filtering can interfere with downlink replies.
  • Keep latency/jitter low; extreme delay or packet loss affects downlinks and joins (see also Architecture).

Basic Station

  • Allow outbound TCP/TLS to the wss:// endpoint; destination port as in the LNS URL or environment (often 4020 or 443).
  • Use TLS inspection on firewalls/proxies only if full WebSocket and certificate forwarding is guaranteed.
  • Prefer a stable WebSocket session; avoid aggressive timeouts or unstable uplinks that drop the session.
  • For certificate validation on the gateway, configure a matching trust chain.

For Both Connection Types

Time, NTP, and Receive Time

Timing is critical for downlinks, join handling, and gateway diagnostics.

Key points:

  • Basic Station primarily uses rxtime
  • UDP / packet-forwarder paths prefer tmms, then time
  • if no reliable gateway time is available, Firefly estimates receive time

The Firefly implementation uses different offsets for estimated timestamps, for example for regular packets and join requests.

Operationally, this means:

  • NTP and, where available, GPS should be configured correctly
  • suspicious time offsets can lead to downlink issues
  • implausible gateway time should be ruled out before deeper troubleshooting

Frequency Plans and Regional Impact

Firefly supports multiple regions, including EU868, US915, AU915, AS923, IN865, KR920, and CN470.

The default region is EU868. At the same time, devices and deployments may use region-specific settings.

For gateways, the main rule is:

Gateway Monitoring in niotix

niotix complements Firefly with monitoring and management functions in IoT Data Hub → Gateway Mgmt. For full UI steps and field descriptions, see IoT Data Hub – Gateway Management.

Typical tasks in niotix:

  • list and filter gateways
  • evaluate aggregated metrics and last-packet activity
  • display Firefly-related gateway IDs and organization relations
  • use thresholds and status logic for operational monitoring

Troubleshooting

When a gateway delivers no or very little payload data, the cause is usually the connectivity model, authentication, time base, or frequency and region parameters. First, establish whether an expected connection to Firefly exists; then review the sections Time, NTP, and Receive Time, Frequency Plans and Regional Impact, and Gateway Monitoring in niotix.

  • Protocol and model: Semtech UDP packet forwarder or Basic Station is chosen consistently with gateway firmware, firewall and ports, and the Firefly setup (see Semtech UDP vs. Basic Station and Firewall and Port Checklist).
  • Basic Station: The gateway is created in Firefly; EUI and auth token match the device values.
  • Time base: NTP/GPS and received timestamps are plausible, without large drift or jumps (see Time, NTP, and Receive Time).
  • Region and channel plan: Gateway settings match the Firefly region and organization (see Frequency Plans and Regional Impact).
  • Firefly: Uplinks or gateway activity are visible there and can be mapped to the expected end devices.
  • niotix: Under Gateway Mgmt, review metrics, last packet activity, and organization mapping; if niotix and Firefly disagree, work through the preceding items in order.

Common Questions

Why does a Basic Station gateway need to be created in Firefly while a UDP gateway does not?

Basic Station uses an authenticated WebSocket connection with an organization-level gateway record. The classic Semtech UDP packet forwarder does not use that management path.

What is the most common reason for apparently stuck downlinks?

The most common reasons are missing reliable uplink data or invalid gateway timing. In that case, Firefly cannot derive a usable gateway or a plausible transmit window.

Why does niotix show a gateway although Firefly does not receive meaningful packets?

In that case, region, channel plan, gateway configuration, and Firefly organization should be checked first. Visibility in niotix does not replace a valid Firefly radio connection.

Why does Gateway Mgmt not show all gateways or load unusually slowly?

This is a recurring support pattern in gateway-related views. Check filters, page size, sorting, data freshness, and Firefly-related gateway mappings first.

Why does a Basic Station gateway still fail even though the URL is correct?

In addition to the URL, Basic Station also requires the correct EUI, auth token, certificate chain, and time base. Unlike the classic UDP forwarder, gateway registration in Firefly is mandatory here. See What must be configured for Basic Station and Basic Station.