README
¶
The Things Stack, an open source LoRaWAN Network Server
The Things Stack 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.0
- Supports LoRaWAN 1.0.1
- Supports LoRaWAN 1.0.2
- Supports LoRaWAN 1.0.3
- Supports LoRaWAN 1.0.4
- Supports LoRaWAN 1.1
- Supports LoRaWAN Regional Parameters 1.0
- Supports LoRaWAN Regional Parameters 1.0.2 rev B
- Supports LoRaWAN Regional Parameters 1.0.3 rev A
- Supports LoRaWAN Regional Parameters 1.1 rev A
- Supports LoRaWAN Regional Parameters 1.1 rev 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
- Implements LoRaWAN Back-end Interfaces 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:
- We will not break the API towards gateways and applications within the major version. This includes how gateways communicate (with Gateway Server) and how applications work with data (with Application Server)
- We will upgrade storage from older versions within the major version via migrations. This means that you can migrate an older setup without losing data.
- We will not require storage migrations within the minor version. This means that you can update patches without database migrations.
- 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 configuration.
- 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.
- We reserve the right to fix bugs in API, configuration and storage in patches and minor updates. This may break components, gateways and applications that rely on buggy behavior.
As we are continuously adding functionality and fixes in new releases, 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
- The forum contains a large amount of information and has great search support. We have a special category for The Things Stack.
- You can chat in the #the-things-stack channel on Slack. If you don't have a Slack account yet, you can create one by going to ttn.fyi/slack-invite.
- Hosted solutions, as well as commercial support and consultancy are offered by The Things Industries.
Documentation
Source Files
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 pub/sub frontend.
|
Package pubsub implements the go-cloud pub/sub frontend. |
|
applicationserver/io/pubsub/provider/mock
Package mock implements a mock pub/sub provider using the mempubsub driver.
|
Package mock implements a mock pub/sub 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. |
|
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. |
|
deviceclaimingserver/enddevices
Package enddevices provides functions to configure End Device claiming clients.
|
Package enddevices provides functions to configure End Device claiming clients. |
|
deviceclaimingserver/enddevices/ttjs
Package ttjs provides the claiming client implementation for The Things Join Server API.
|
Package ttjs provides the claiming client implementation for The Things Join Server API. |
|
devicerepository
Package devicerepository integrates with the Device Repository.
|
Package devicerepository integrates with 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. |
|
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/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. |
|
gatewayserver/upstream/packetbroker
Package packetbroker abstracts the Packet Broker Agent to the upstream.Handler interface.
|
Package packetbroker abstracts the Packet Broker Agent 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. |
|
identityserver/mock
Package mockis provides a mock structure to the Identity Server.
|
Package mockis provides a mock structure to the Identity Server. |
|
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/middleware/observability
Package observability implements a pkg/log.Handler that exports metrics for the logged messages.
|
Package observability implements a pkg/log.Handler that exports metrics for the logged messages. |
|
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 |
|
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/internal
Internal package contains various Network Server utilities
|
Internal package contains various Network Server utilities |
|
networkserver/internal/test
Package test contains testing utilities usable by all subpackages of networkserver including itself.
|
Package test contains testing utilities usable by all subpackages of networkserver including itself. |
|
networkserver/internal/test/shared
Package test contains testing utilities usable by all subpackages of networkserver excluding itself.
|
Package test contains testing utilities usable by all subpackages of networkserver excluding itself. |
|
networkserver/internal/time
Package time wraps "time" and allows for custom implementations of key functions.
|
Package time wraps "time" and allows for custom implementations of key functions. |
|
networkserver/redis
Package redis provides Redis implementations of interfaces used by networkserver.
|
Package redis provides Redis implementations of interfaces used by networkserver. |
|
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/lbslns
Package lbslns implements the JSON configuration for the LoRa Basics Station `router_config` message.
|
Package lbslns implements the JSON configuration for the LoRa Basics Station `router_config` message. |
|
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. |
|
redis/codec
Package codec provides a codec, which encodes and decodes protocol buffers stored in Redis to/from JSON.
|
Package codec provides a codec, which encodes and decodes protocol buffers stored in Redis to/from JSON. |
|
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/byteutil
Package byteutil provides utilities for working with bytes using little endian binary encoding.
|
Package byteutil provides utilities for working with bytes using little endian binary encoding. |
|
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. |
|
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. |
|
webmiddleware
Package webmiddleware provides middleware for http Handlers.
|
Package webmiddleware provides middleware for http Handlers. |
Click to show internal directories.
Click to hide internal directories.