README

The Things Stack for LoRaWAN

Build Status Coverage Status

The Things Stack for LoRaWAN is an open source LoRaWAN network stack suitable for large, global and geo-distributed public and private networks as well as smaller networks. The architecture follows the LoRaWAN Network Reference Model for standards compliancy and interoperability. This project is actively maintained by The Things Industries.

LoRaWAN is a protocol for low-power wide area networks. It allows for large scale Internet of Things deployments where low-powered devices efficiently communicate with Internet-connected applications over long range wireless connections.

Features

  • LoRaWAN Network Server
    • Supports LoRaWAN 1.1
    • Supports LoRaWAN 1.0, 1.0.1, 1.0.2 and 1.0.3
    • Supports LoRaWAN Regional Parameters 1.0, 1.0.2 rev B, 1.0.3 rev A, 1.1 rev A and B
    • Supports Class A devices
    • Supports Class B devices
    • Supports Class C devices
    • Supports OTAA devices
    • Supports ABP devices
    • Supports MAC Commands
    • Supports Adaptive Data Rate
    • Implements LoRaWAN Back-end Interfaces 1.0
  • LoRaWAN Application Server
    • Payload conversion of well-known payload formats
    • Payload conversion using custom JavaScript functions
    • MQTT pub/sub API
    • HTTP Webhooks API
    • Implements LoRaWAN Back-end Interfaces 1.0
  • LoRaWAN Join Server
    • Supports OTAA session key derivation
    • Supports external crypto services
    • Implements LoRaWAN Back-end Interfaces 1.0 and 1.1 draft 3
  • OAuth 2.0 Identity Server
    • User management
    • Entity management
    • ACLs
  • GRPC APIs
  • HTTP APIs
  • Command-Line Interface
    • Create account and login
    • Application management and traffic
    • End device management, status and traffic
    • Gateway management and status
  • Web Interface (Console)
    • Create account and login
    • Application management and traffic
    • End device management, status and traffic
    • Gateway management, status and traffic

Getting Started

You want to install The Things Stack? Fantastic! Here's the Getting Started guide.

Do you want to set up a local development environment? See the DEVELOPMENT.md for instructions.

Do you want to contribute to The Things Stack? Your contributions are welcome! See the guidelines in CONTRIBUTING.md.

Are you new to LoRaWAN and The Things Network? See the general documentation at thethingsnetwork.org/docs.

Commitments and Releases

Open source projects are great, but a stable and reliable open source ecosystem is even better. Therefore, we make the following commitments:

  1. We will not break the API towards gateways and applications within the major version. This includes how gateways communicate and how applications work with data
  2. We will upgrade storage from older versions within the major version. This means that you can migrate an older setup without losing data
  3. We will not break the public command-line interface and configuration within the major version. This means that you can safely build scripts and migrate configurations
  4. We will not break the API between components and events within minor versions. So at least the same minor versions of components are compatible with each other

As we are continuously adding functionality in minor versions and fixing issues in patch versions, we are also introducing new configurations and new defaults. We therefore recommend reading the release notes before upgrading to a new version.

You can find the releases and their notes on the Releases page.

Support

Documentation

Overview

    Package stack contains The Things Stack for LoRaWAN.

    Directories

    Path Synopsis
    cmd
    ttn-lw-cli
    ttn-lw-cli is the binary for the Command-line interface of The Things Stack for LoRaWAN.
    ttn-lw-cli is the binary for the Command-line interface of The Things Stack for LoRaWAN.
    ttn-lw-cli/commands
    Package commands implements the commands for the ttn-lw-cli binary.
    Package commands implements the commands for the ttn-lw-cli binary.
    ttn-lw-stack
    ttn-lw-stack is the binary that runs the entire The Things Stack for LoRaWAN.
    ttn-lw-stack is the binary that runs the entire The Things Stack for LoRaWAN.
    ttn-lw-stack/commands
    Package commands implements the commands for the ttn-lw-stack binary.
    Package commands implements the commands for the ttn-lw-stack binary.
    pkg
    applicationserver/io/mqtt
    Package mqtt implements the MQTT frontend.
    Package mqtt implements the MQTT frontend.
    applicationserver/io/pubsub
    Package pubsub implements the go-cloud PubSub frontend.
    Package pubsub implements the go-cloud PubSub frontend.
    applicationserver/io/pubsub/provider/mock
    Package mock implements a mock PubSub provider using the mempubsub driver.
    Package mock implements a mock PubSub provider using the mempubsub driver.
    applicationserver/io/pubsub/provider/mqtt
    Package mqtt implements the MQTT provider using the mqtt driver.
    Package mqtt implements the MQTT provider using the mqtt driver.
    applicationserver/io/pubsub/provider/nats
    Package nats implements the NATS provider using the natspubsub driver.
    Package nats implements the NATS provider using the natspubsub driver.
    applicationserver/io/web
    Package web implements the webhooks integration.
    Package web implements the webhooks integration.
    auth
    Package auth provides methods to generate valid authorization values and to also decode them.
    Package auth provides methods to generate valid authorization values and to also decode them.
    auth/cluster
    Package cluster contains cluster authentication-related utilities.
    Package cluster contains cluster authentication-related utilities.
    auth/pbkdf2
    Package pbkdf2 implements the PBKDF2 algorithm method used to hash passwords.
    Package pbkdf2 implements the PBKDF2 algorithm method used to hash passwords.
    auth/rights
    Package rights implements rights fetching and checking.
    Package rights implements rights fetching and checking.
    band
    Package band contains structs to handle regional bands.
    Package band contains structs to handle regional bands.
    cluster
    Package cluster defines an interface for clustering network components and provides a simple implementation.
    Package cluster defines an interface for clustering network components and provides a simple implementation.
    component
    Package component contains the methods and structures common to all components.
    Package component contains the methods and structures common to all components.
    config
    Package config wraps Viper.
    Package config wraps Viper.
    config/example
    example cobra command with config.
    example cobra command with config.
    crypto
    Package crypto implements LoRaWAN crypto.
    Package crypto implements LoRaWAN crypto.
    devicerepository
    Package devicerepository allows to fetch device data from the Device Repository.
    Package devicerepository allows to fetch device data from the Device Repository.
    devicetemplateconverter
    Package devicetemplateconverter provides device template services.
    Package devicetemplateconverter provides device template services.
    devicetemplates
    Package devicetemplates implements creating templates for devices.
    Package devicetemplates implements creating templates for devices.
    email
    Package email provides an interface to send messages over email.
    Package email provides an interface to send messages over email.
    email/mock
    Package mock provides a test email provider that is used in tests.
    Package mock provides a test email provider that is used in tests.
    email/sendgrid
    Package sendgrid provides the implementation of an email sender using SendGrid.
    Package sendgrid provides the implementation of an email sender using SendGrid.
    encoding/lorawan
    Package lorawan provides LoRaWAN decoding/encoding interfaces.
    Package lorawan provides LoRaWAN decoding/encoding interfaces.
    errorcontext
    Package errorcontext implements a Context that can be canceled with a specific error instead of the usual context.Canceled.
    Package errorcontext implements a Context that can be canceled with a specific error instead of the usual context.Canceled.
    errors
    Package errors implements rich errors that carry contextual information such as stack traces, causality and attributes.
    Package errors implements rich errors that carry contextual information such as stack traces, causality and attributes.
    errors/web
    Package web implements a middleware to handle HTTP errors.
    Package web implements a middleware to handle HTTP errors.
    events
    Package events implements event handling through a PubSub interface.
    Package events implements event handling through a PubSub interface.
    events/cloud
    Package cloud implements an events.PubSub implementation that uses Go Cloud PubSub.
    Package cloud implements an events.PubSub implementation that uses Go Cloud PubSub.
    events/fs
    Package fs implements watching files for changes.
    Package fs implements watching files for changes.
    events/grpc
    Package grpc contains an implementation of the EventsServer, which is used to stream all events published for a set of identifiers.
    Package grpc contains an implementation of the EventsServer, which is used to stream all events published for a set of identifiers.
    events/redis
    Package redis implements an events.PubSub implementation that uses Redis PubSub.
    Package redis implements an events.PubSub implementation that uses Redis PubSub.
    fetch
    Package fetch offers abstractions to fetch a file with the same method, regardless of a location (filesystem, HTTP...).
    Package fetch offers abstractions to fetch a file with the same method, regardless of a location (filesystem, HTTP...).
    fillcontext
    Package fillcontext implements a mechanism to fill contexts.
    Package fillcontext implements a mechanism to fill contexts.
    frequencyplans
    Package frequencyplans contains abstractions to fetch and manipulate frequency plans.
    Package frequencyplans contains abstractions to fetch and manipulate frequency plans.
    gatewayserver
    Package gatewayserver contains the structs and methods necessary to start a gRPC Gateway Server
    Package gatewayserver contains the structs and methods necessary to start a gRPC Gateway Server
    gatewayserver/scheduling
    Package scheduling implements a packet scheduling that detects and avoids conflicts and enforces regional restrictions like duty-cycle and dwell time.
    Package scheduling implements a packet scheduling that detects and avoids conflicts and enforces regional restrictions like duty-cycle and dwell time.
    gatewayserver/upstream/mock
    Package mock provides mock implementation of necessary NS interfaces for testing.
    Package mock provides mock implementation of necessary NS interfaces for testing.
    gatewayserver/upstream/ns
    Package ns abstracts the V3 Network Server to the upstream.Handler interface.
    Package ns abstracts the V3 Network Server to the upstream.Handler interface.
    gogoproto
    Package gogoproto implements conversions from well-known gogo/profobuf types.
    Package gogoproto implements conversions from well-known gogo/profobuf types.
    goproto
    Package goproto implements conversions from well-known golang/profobuf types.
    Package goproto implements conversions from well-known golang/profobuf types.
    gpstime
    Package gpstime provides utilities to work with GPS time.
    Package gpstime provides utilities to work with GPS time.
    i18n
    Package i18n helps with internationalization of registered messages.
    Package i18n helps with internationalization of registered messages.
    joinserver
    Package joinserver provides a LoRaWAN-compliant Join Server implementation.
    Package joinserver provides a LoRaWAN-compliant Join Server implementation.
    joinserver/redis
    Package redis provides Redis implementations of interfaces used by joinserver.
    Package redis provides Redis implementations of interfaces used by joinserver.
    log
    Package log contains all the structs to log TTN.
    Package log contains all the structs to log TTN.
    log/handler/memory
    Package memory implements a pkg/log.Handler that saves all entries in process memory
    Package memory implements a pkg/log.Handler that saves all entries in process memory
    log/handler/multi
    Package multi implements a pkg/log.Handler that applies every log message on multiple Handlers
    Package multi implements a pkg/log.Handler that applies every log message on multiple Handlers
    log/middleware/sentry
    Package sentry implements a pkg/log.Handler that sends errors to Sentry
    Package sentry implements a pkg/log.Handler that sends errors to Sentry
    log/test
    Package test exposes simple implementations of log interfaces that can be used for testing.
    Package test exposes simple implementations of log interfaces that can be used for testing.
    messageprocessors
    Package messageprocessors provides interfaces and implementations for processing uplink and downlink messages.
    Package messageprocessors provides interfaces and implementations for processing uplink and downlink messages.
    messageprocessors/cayennelpp
    Package cayennelpp contains the CayenneLPP payload formatter message processors.
    Package cayennelpp contains the CayenneLPP payload formatter message processors.
    messageprocessors/javascript
    Package javascript contains the Javascript payload formatter message processors.
    Package javascript contains the Javascript payload formatter message processors.
    metrics
    Package metrics creates the metrics registry and exposes some common metrics.
    Package metrics creates the metrics registry and exposes some common metrics.
    mqtt
    Package mqtt contains MQTT-related utilities.
    Package mqtt contains MQTT-related utilities.
    networkserver
    Package networkserver provides a LoRaWAN-compliant Network Server implementation.
    Package networkserver provides a LoRaWAN-compliant Network Server implementation.
    networkserver/redis
    Package redis provides Redis implementations of interfaces used by networkserver.
    Package redis provides Redis implementations of interfaces used by networkserver.
    pfconfig/basicstationlns
    Package basicstationlns implements the JSON configuration for the Basic Station `router_config` message.
    Package basicstationlns implements the JSON configuration for the Basic Station `router_config` message.
    pfconfig/cpf
    Package cpf implements the JSON configuration for the Common Packet Forwarder.
    Package cpf implements the JSON configuration for the Common Packet Forwarder.
    pfconfig/semtechudp
    Package semtechudp implements the JSON configuration for the Semtech UDP Packet Forwarder.
    Package semtechudp implements the JSON configuration for the Semtech UDP Packet Forwarder.
    pfconfig/shared
    Package shared contains the configuration that is common to various gateway types.
    Package shared contains the configuration that is common to various gateway types.
    provisioning
    Package provisioning provides a registry and implementations of vendor-specific device provisioners.
    Package provisioning provides a registry and implementations of vendor-specific device provisioners.
    qrcode
    Package qrcode implements working with QR codes.
    Package qrcode implements working with QR codes.
    qrcodegenerator
    Package qrcodegenerator provides QR code generation services.
    Package qrcodegenerator provides QR code generation services.
    random
    Package random implements goroutine-safe utilities on top of a secure random source.
    Package random implements goroutine-safe utilities on top of a secure random source.
    redis
    Package redis provides a general Redis client and utilities.
    Package redis provides a general Redis client and utilities.
    rpcclient
    Package rpcclient contains the default options for TTN gRPC clients.
    Package rpcclient contains the default options for TTN gRPC clients.
    rpcmetadata
    Package rpcmetadata contains utilities for transporting common request metadata over gRPC.
    Package rpcmetadata contains utilities for transporting common request metadata over gRPC.
    rpcmiddleware/discover
    Package discover implements a gRPC discovery middleware.
    Package discover implements a gRPC discovery middleware.
    rpcmiddleware/fillcontext
    Package fillcontext implements a gRPC middleware that fills global context into a call context.
    Package fillcontext implements a gRPC middleware that fills global context into a call context.
    rpcmiddleware/hooks
    Package hooks implements a gRPC middleware that executes service and method hooks.
    Package hooks implements a gRPC middleware that executes service and method hooks.
    rpcmiddleware/rpclog
    Package rpclog implements a gRPC logging middleware.
    Package rpclog implements a gRPC logging middleware.
    rpcmiddleware/sentry
    Package sentry implements gRPC middleware that forwards errors in RPCs to Sentry
    Package sentry implements gRPC middleware that forwards errors in RPCs to Sentry
    rpcmiddleware/validator
    Package validator implements a gRPC middleware that defines custom validators that are invoked when the service is called.
    Package validator implements a gRPC middleware that defines custom validators that are invoked when the service is called.
    rpcmiddleware/warning
    Package warning communicates warnings over gRPC headers.
    Package warning communicates warnings over gRPC headers.
    rpcserver
    Package rpcserver initializes The Things Network's base gRPC server
    Package rpcserver initializes The Things Network's base gRPC server
    scripting
    Package scripting provides a generic abstraction layer for running scripts at runtime.
    Package scripting provides a generic abstraction layer for running scripts at runtime.
    scripting/javascript
    Package javascript implements a Javascript scripting engine.
    Package javascript implements a Javascript scripting engine.
    toa
    Package toa provides methods for computing a LoRaWAN packet's time-on-air.
    Package toa provides methods for computing a LoRaWAN packet's time-on-air.
    ttnpb
    Package ttnpb is a reverse proxy.
    Package ttnpb is a reverse proxy.
    types
    Package types contains basic types that are used in The Things Network's protobuf messages.
    Package types contains basic types that are used in The Things Network's protobuf messages.
    unique
    Package unique provides functionality for working with unique identifiers of entities within a context.
    Package unique provides functionality for working with unique identifiers of entities within a context.
    util
    Package util contains various utilities.
    Package util contains various utilities.
    util/randutil
    Package randutil provides pseudo-random number generator utilities.
    Package randutil provides pseudo-random number generator utilities.
    util/rpctest
    Package rpctest is a generated protocol buffer package.
    Package rpctest is a generated protocol buffer package.
    util/test
    Package test provides various testing utilities.
    Package test provides various testing utilities.
    util/test/assertions
    Package assertions contains custom assertions compatible with github.com/smartystreets/assertions.
    Package assertions contains custom assertions compatible with github.com/smartystreets/assertions.
    util/test/assertions/should
    Package should wraps assertions in github.com/smartystreets/assertions and util/test/assertions.
    Package should wraps assertions in github.com/smartystreets/assertions and util/test/assertions.
    validate
    Package validate implements validation functions, usually used RPC message validation.
    Package validate implements validation functions, usually used RPC message validation.
    version
    Package version contains version and build variables set by the CI process.
    Package version contains version and build variables set by the CI process.
    web
    tools module