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

Expand ▾ Collapse ▴

Documentation

Overview

Package stack contains The Things Stack for LoRaWAN.

Source Files

Directories

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