networkserver

Documentation

Overview

Package networkserver provides a LoRaWAN-compliant Network Server implementation.

Index

• Constants
• Variables
• type ApplicationUplinkQueue
• type Config
• type DeviceRegistry
• type DownlinkPriorities
• type DownlinkPriorityConfig
  • func (c DownlinkPriorityConfig) Parse() (DownlinkPriorities, error)
• type DownlinkTaskQueue
• type InteropClient
• type MACHandler
• type MACSettingConfig
  • func (c MACSettingConfig) Parse() ttnpb.MACSettings
• type NetworkServer
  • func New(c *component.Component, conf *Config, opts ...Option) (*NetworkServer, error)
  • func (ns *NetworkServer) Context() context.Context
  • func (ns *NetworkServer) Delete(ctx context.Context, req *ttnpb.EndDeviceIdentifiers) (*pbtypes.Empty, error)
  • func (ns *NetworkServer) DownlinkQueueList(ctx context.Context, ids *ttnpb.EndDeviceIdentifiers) (*ttnpb.ApplicationDownlinks, error)
  • func (ns *NetworkServer) DownlinkQueuePush(ctx context.Context, req *ttnpb.DownlinkQueueRequest) (*pbtypes.Empty, error)
  • func (ns *NetworkServer) DownlinkQueueReplace(ctx context.Context, req *ttnpb.DownlinkQueueRequest) (*pbtypes.Empty, error)
  • func (ns *NetworkServer) GenerateDevAddr(ctx context.Context, req *types.Empty) (*ttnpb.GenerateDevAddrResponse, error)
  • func (ns *NetworkServer) Get(ctx context.Context, req *ttnpb.GetEndDeviceRequest) (*ttnpb.EndDevice, error)
  • func (ns *NetworkServer) HandleUplink(ctx context.Context, up *ttnpb.UplinkMessage) (_ *pbtypes.Empty, err error)
  • func (ns *NetworkServer) LinkApplication(link ttnpb.AsNs_LinkApplicationServer) error
  • func (ns *NetworkServer) RegisterHandlers(s *runtime.ServeMux, conn *grpc.ClientConn)
  • func (ns *NetworkServer) RegisterServices(s *grpc.Server)
  • func (ns *NetworkServer) Roles() []ttnpb.ClusterRole
  • func (ns *NetworkServer) Set(ctx context.Context, req *ttnpb.SetEndDeviceRequest) (dev *ttnpb.EndDevice, err error)
• type Option
• type UplinkDeduplicator

Constants

const (
	DefaultStatusCountPeriodicity uint32 = 200
	DefaultStatusTimePeriodicity         = 24 * time.Hour
)

const DefaultADRMargin = 15

DefaultADRMargin is the default ADR margin used if not specified in MACSettings of the device or NS-wide defaults.

const DefaultClassBTimeout = 10 * time.Minute

DefaultClassBTimeout is the default time-out for the device to respond to class B downlink messages. When waiting for a response times out, the downlink message is considered lost, and the downlink task triggers again.

const DefaultClassCTimeout = 5 * time.Minute

DefaultClassCTimeout is the default time-out for the device to respond to class C downlink messages. When waiting for a response times out, the downlink message is considered lost, and the downlink task triggers again.

Variables

var DefaultConfig = Config{
	DeduplicationWindow: 200 * time.Millisecond,
	CooldownWindow:      time.Second,
	DownlinkPriorities: DownlinkPriorityConfig{
		JoinAccept:             "highest",
		MACCommands:            "highest",
		MaxApplicationDownlink: "high",
	},
	DefaultMACSettings: MACSettingConfig{
		ADRMargin:              func(v float32) *float32 { return &v }(DefaultADRMargin),
		DesiredRx1Delay:        func(v ttnpb.RxDelay) *ttnpb.RxDelay { return &v }(ttnpb.RX_DELAY_5),
		ClassBTimeout:          func(v time.Duration) *time.Duration { return &v }(time.Minute),
		ClassCTimeout:          func(v time.Duration) *time.Duration { return &v }(DefaultClassCTimeout),
		StatusTimePeriodicity:  func(v time.Duration) *time.Duration { return &v }(DefaultStatusTimePeriodicity),
		StatusCountPeriodicity: func(v uint32) *uint32 { return &v }(DefaultStatusCountPeriodicity),
	},
}

var DefaultOptions []Option

Types

type ApplicationUplinkQueue

type ApplicationUplinkQueue interface {
	// Add adds application uplinks ups to queue.
	// Implementations must ensure that Add returns fast.
	Add(ctx context.Context, ups ...*ttnpb.ApplicationUp) error

	// Subscribe calls f sequentially for each application uplink in the queue.
	// If f returns a non-nil error or ctx is done, Subscribe stops the iteration.
	// TODO: Use ...*ttnpb.ApplicationUp in callback once https://github.com/TheThingsNetwork/lorawan-stack/issues/1523 is implemented.
	Subscribe(ctx context.Context, appID ttnpb.ApplicationIdentifiers, f func(context.Context, *ttnpb.ApplicationUp) error) error
}

type Config

type Config struct {
	ApplicationUplinks  ApplicationUplinkQueue `name:"-"`
	Devices             DeviceRegistry         `name:"-"`
	DownlinkTasks       DownlinkTaskQueue      `name:"-"`
	UplinkDeduplicator  UplinkDeduplicator     `name:"-"`
	NetID               types.NetID            `name:"net-id" description:"NetID of this Network Server"`
	DevAddrPrefixes     []types.DevAddrPrefix  `name:"dev-addr-prefixes" description:"Device address prefixes of this Network Server"`
	DeduplicationWindow time.Duration          `name:"deduplication-window" description:"Time window during which, duplicate messages are collected for metadata"`
	CooldownWindow      time.Duration          `` /* 138-byte string literal not displayed */
	DownlinkPriorities  DownlinkPriorityConfig `name:"downlink-priorities" description:"Downlink message priorities"`
	DefaultMACSettings  MACSettingConfig       `` /* 128-byte string literal not displayed */
	Interop             config.InteropClient   `name:"interop" description:"Interop client configuration"`
	DeviceKEKLabel      string                 `name:"device-kek-label" description:"Label of KEK used to encrypt device keys at rest"`
}

Config represents the NetworkServer configuration.

type DeviceRegistry

type DeviceRegistry interface {
	GetByEUI(ctx context.Context, joinEUI, devEUI types.EUI64, paths []string) (*ttnpb.EndDevice, context.Context, error)
	GetByID(ctx context.Context, appID ttnpb.ApplicationIdentifiers, devID string, paths []string) (*ttnpb.EndDevice, context.Context, error)
	RangeByAddr(ctx context.Context, devAddr types.DevAddr, paths []string, f func(context.Context, *ttnpb.EndDevice) bool) error
	SetByID(ctx context.Context, appID ttnpb.ApplicationIdentifiers, devID string, paths []string, f func(context.Context, *ttnpb.EndDevice) (*ttnpb.EndDevice, []string, error)) (*ttnpb.EndDevice, context.Context, error)
}

DeviceRegistry is a registry, containing devices.

type DownlinkPriorities

type DownlinkPriorities struct {
	// JoinAccept is the downlink priority for join-accept messages.
	JoinAccept,

	MACCommands,

	MaxApplicationDownlink ttnpb.TxSchedulePriority
}

DownlinkPriorities define the schedule priorities for the different types of downlink.

type DownlinkPriorityConfig

type DownlinkPriorityConfig struct {
	// JoinAccept is the downlink priority for join-accept messages.
	JoinAccept string `` /* 131-byte string literal not displayed */
	// MACCommands is the downlink priority for downlink messages with MAC commands as FRMPayload (FPort = 0) or as FOpts.
	// If the MAC commands are carried in FOpts, the highest priority of this value and the concerning application
	// downlink message's priority is used.
	MACCommands string `` /* 142-byte string literal not displayed */
	// MaxApplicationDownlink is the highest priority permitted by the Network Server for application downlink.
	MaxApplicationDownlink string `` /* 161-byte string literal not displayed */
}

DownlinkPriorityConfig defines priorities for downlink messages.

func (DownlinkPriorityConfig) Parse

func (c DownlinkPriorityConfig) Parse() (DownlinkPriorities, error)

Parse attempts to parse the configuration and returns a DownlinkPriorities.

type DownlinkTaskQueue

type DownlinkTaskQueue interface {
	// Add adds downlink task for device identified by devID at time t.
	// Implementations must ensure that Add returns fast.
	Add(ctx context.Context, devID ttnpb.EndDeviceIdentifiers, t time.Time, replace bool) error

	// Pop calls f on the most recent downlink task in the schedule, for which timestamp is in range [0, time.Now()],
	// if such is available, otherwise it blocks until it is.
	// Context passed to f must be derived from ctx.
	// Implementations must respect ctx.Deadline() value on best-effort basis, if such is present.
	Pop(ctx context.Context, f func(context.Context, ttnpb.EndDeviceIdentifiers, time.Time) error) error
}

DownlinkTaskQueue represents an entity, that holds downlink tasks sorted by timestamp.

type InteropClient

type InteropClient interface {
	HandleJoinRequest(context.Context, types.NetID, *ttnpb.JoinRequest) (*ttnpb.JoinResponse, error)
}

InteropClient is a client, which Network Server can use for interoperability.

type MACHandler

type MACHandler func(ctx context.Context, dev *ttnpb.EndDevice, pld []byte, up *ttnpb.UplinkMessage) error

MACHandler defines the behavior of a MAC command on a device.

type MACSettingConfig

type MACSettingConfig struct {
	ADRMargin                  *float32                   `` /* 135-byte string literal not displayed */
	DesiredRx1Delay            *ttnpb.RxDelay             `` /* 130-byte string literal not displayed */
	DesiredMaxDutyCycle        *ttnpb.AggregatedDutyCycle `` /* 139-byte string literal not displayed */
	DesiredADRAckLimitExponent *ttnpb.ADRAckLimitExponent `` /* 148-byte string literal not displayed */
	DesiredADRAckDelayExponent *ttnpb.ADRAckDelayExponent `` /* 148-byte string literal not displayed */
	ClassBTimeout              *time.Duration             `` /* 164-byte string literal not displayed */
	ClassCTimeout              *time.Duration             `` /* 164-byte string literal not displayed */
	StatusTimePeriodicity      *time.Duration             `` /* 170-byte string literal not displayed */
	StatusCountPeriodicity     *uint32                    `` /* 184-byte string literal not displayed */
}

MACSettingConfig defines MAC-layer configuration.

func (MACSettingConfig) Parse

func (c MACSettingConfig) Parse() ttnpb.MACSettings

Parse parses the configuration and returns ttnpb.MACSettings.

type NetworkServer

type NetworkServer struct {
	*component.Component
	// contains filtered or unexported fields
}

NetworkServer implements the Network Server component.

The Network Server exposes the GsNs, AsNs, DeviceRegistry and ApplicationDownlinkQueue services.

func New

func New(c *component.Component, conf *Config, opts ...Option) (*NetworkServer, error)

New returns new NetworkServer.

func (*NetworkServer) Context

func (ns *NetworkServer) Context() context.Context

Context returns the context of the Network Server.

func (*NetworkServer) Delete

func (ns *NetworkServer) Delete(ctx context.Context, req *ttnpb.EndDeviceIdentifiers) (*pbtypes.Empty, error)

Delete implements NsEndDeviceRegistryServer.

func (*NetworkServer) DownlinkQueueList

func (ns *NetworkServer) DownlinkQueueList(ctx context.Context, ids *ttnpb.EndDeviceIdentifiers) (*ttnpb.ApplicationDownlinks, error)

DownlinkQueueList is called by the Application Server to get the current state of the downlink queue for a device.

func (*NetworkServer) DownlinkQueuePush

func (ns *NetworkServer) DownlinkQueuePush(ctx context.Context, req *ttnpb.DownlinkQueueRequest) (*pbtypes.Empty, error)

DownlinkQueuePush is called by the Application Server to push a downlink to queue for a device.

func (*NetworkServer) DownlinkQueueReplace

func (ns *NetworkServer) DownlinkQueueReplace(ctx context.Context, req *ttnpb.DownlinkQueueRequest) (*pbtypes.Empty, error)

DownlinkQueueReplace is called by the Application Server to completely replace the downlink queue for a device.

func (*NetworkServer) GenerateDevAddr

func (ns *NetworkServer) GenerateDevAddr(ctx context.Context, req *types.Empty) (*ttnpb.GenerateDevAddrResponse, error)

GenerateDevAddr returns a device address assignment in the device address range of the network server.

func (*NetworkServer) Get

func (ns *NetworkServer) Get(ctx context.Context, req *ttnpb.GetEndDeviceRequest) (*ttnpb.EndDevice, error)

Get implements NsEndDeviceRegistryServer.

func (*NetworkServer) HandleUplink

func (ns *NetworkServer) HandleUplink(ctx context.Context, up *ttnpb.UplinkMessage) (_ *pbtypes.Empty, err error)

HandleUplink is called by the Gateway Server when an uplink message arrives.

func (*NetworkServer) LinkApplication

func (ns *NetworkServer) LinkApplication(link ttnpb.AsNs_LinkApplicationServer) error

LinkApplication is called by the Application Server to subscribe to application events.

func (*NetworkServer) RegisterHandlers

func (ns *NetworkServer) RegisterHandlers(s *runtime.ServeMux, conn *grpc.ClientConn)

RegisterHandlers registers gRPC handlers.

func (*NetworkServer) RegisterServices

func (ns *NetworkServer) RegisterServices(s *grpc.Server)

RegisterServices registers services provided by ns at s.

func (*NetworkServer) Roles

func (ns *NetworkServer) Roles() []ttnpb.ClusterRole

Roles returns the roles that the Network Server fulfills.

func (*NetworkServer) Set

func (ns *NetworkServer) Set(ctx context.Context, req *ttnpb.SetEndDeviceRequest) (dev *ttnpb.EndDevice, err error)

Set implements NsEndDeviceRegistryServer.

type Option

type Option func(ns *NetworkServer)

Option configures the NetworkServer.

type UplinkDeduplicator

type UplinkDeduplicator interface {
	// DeduplicateUplink deduplicates an uplink message for specified time.Duration.
	// DeduplicateUplink returns true if the uplink is not a duplicate or false and error, if any, otherwise.
	DeduplicateUplink(context.Context, *ttnpb.UplinkMessage, time.Duration) (bool, error)
	// AccumulatedMetadata returns accumulated metadata for specified uplink message and error, if any.
	AccumulatedMetadata(context.Context, *ttnpb.UplinkMessage) ([]*ttnpb.RxMetadata, error)
}

UplinkDeduplicator represents an entity, that deduplicates uplinks and accumulates metadata.