API Reference
Outdated: this section documents The Things Network V2, which is no longer maintained. See the documentation for The Things Stack V3, or browse the V2 docs index.
import ttnsdk "github.com/TheThingsNetwork/go-app-sdk"
Package ttnsdk implements the Go SDK for The Things Network.
This package wraps The Things Network’s application and device management APIs (github.com/TheThingsNetwork/api) and the publish/subscribe API (github.com/TheThingsNetwork/ttn/mqtt). It works with the Discovery Server to retrieve the addresses of the Handler and MQTT server.
Variables #
var ClientVersion = "2.x.x"
ClientVersion to use
var DialOptions = []grpc.DialOption{
grpc.WithUnaryInterceptor(grpc_middleware.ChainUnaryClient(
rpclog.UnaryClientInterceptor(nil),
)),
grpc.WithStreamInterceptor(grpc_middleware.ChainStreamClient(
restartstream.Interceptor(restartstream.DefaultSettings),
rpclog.StreamClientInterceptor(nil),
)),
grpc.WithBlock(),
}
DialOptions to use when connecting to components
func MoveDevice #
func MoveDevice(devID string, from, to DeviceManager) (err error)
MoveDevice moves a device to another application
type ApplicationManager #
type ApplicationManager interface {
// Get the payload format used in this application. If the payload format is "custom", you can get the custom JS
// payload functions with the GetCustomPayloadFunctions() function.
GetPayloadFormat() (string, error)
// Set the payload format to use in this application. If you want to use custom JS payload functions, use the
// SetCustomPayloadFunctions() function instead. If you want to disable payload conversion, pass an empty string.
SetPayloadFormat(format string) error
// Get the custom JS payload functions.
GetCustomPayloadFunctions() (jsDecoder, jsConverter, jsValidator, jsEncoder string, err error)
// Set the custom JS payload functions.
//
// Example Decoder:
//
// // Decoder (Array<byte>, uint8) returns (Object)
// function Decoder(bytes, port) {
// var decoded = {};
// return decoded;
// }
//
// Example Converter:
//
// // Converter (Object, uint8) returns (Object)
// function Converter(decoded, port) {
// var converted = decoded;
// return converted;
// }
//
// Example Validator:
// // Validator (Object, uint8) returns (Boolean)
// function Validator(converted, port) {
// return true;
// }
//
// Example Encoder:
//
// // Validator (Object, uint8) returns (Array<byte>)
// function Encoder(object, port) {
// var bytes = [];
// return bytes;
// }
SetCustomPayloadFunctions(jsDecoder, jsConverter, jsValidator, jsEncoder string) error
}
ApplicationManager manages an application.
type ApplicationPubSub #
type ApplicationPubSub interface {
Publish(devID string, downlink *types.DownlinkMessage) error
Device(devID string) DevicePubSub
AllDevices() DeviceSub
Close()
}
ApplicationPubSub interface for publishing and subscribing to devices in an application
type Client #
type Client interface {
// Close the client and clean up all connections
Close() error
// Subscribe to uplink and events, publish downlink
PubSub() (ApplicationPubSub, error)
// Manage the application
ManageApplication() (ApplicationManager, error)
// Manage devices in the application
ManageDevices() (DeviceManager, error)
// Simulate uplink messages for a device (for testing)
Simulate(devID string) (Simulator, error)
}
Client interface for The Things Network’s API.
type ClientConfig #
type ClientConfig struct {
Logger log.Interface
// The name of this client
ClientName string
// The version of this client (in the default config, this is the value of ttnsdk.ClientVersion)
ClientVersion string
// TLS Configuration only has to be set if connecting with servers that do not have trusted certificates.
TLSConfig *tls.Config
// Address of the Account Server (in the default config, this is https://account.thethingsnetwork.org)
AccountServerAddress string
// Client ID for the account server (if you registered your client)
AccountServerClientID string
// Client Secret for the account server (if you registered your client)
AccountServerClientSecret string
// Address of the Discovery Server (in the default config, this is discovery.thethings.network:1900)
DiscoveryServerAddress string
// Set this to true if the Discovery Server is insecure (not recommended)
DiscoveryServerInsecure bool
// Address of the Handler (optional)
HandlerAddress string
// Timeout for requests (in the default config, this is 10 seconds)
RequestTimeout time.Duration
}
ClientConfig contains the configuration for the API client. Use the NewConfig() or NewCommunityConfig() functions to initialize your configuration, otherwise NewClient will panic.
func NewCommunityConfig #
func NewCommunityConfig(clientName string) ClientConfig
NewCommunityConfig creates a new configuration for the API client that is pre-configured for the The Things Stack Sandbox.
func NewConfig #
func NewConfig(clientName, accountServerAddress, discoveryServerAddress string) ClientConfig
NewConfig creates a new configuration for the API client.
func (ClientConfig) NewClient #
func (c ClientConfig) NewClient(appID, appAccessKey string) Client
NewClient creates a new API client from the configuration, using the given Application ID and Application access key.
type Device #
type Device struct {
SparseDevice
FCntUp uint32 `json:"f_cnt_up"`
FCntDown uint32 `json:"f_cnt_down"`
DisableFCntCheck bool `json:"disable_f_cnt_check"`
Uses32BitFCnt bool `json:"uses32_bit_f_cnt"`
ActivationConstraints string `json:"activation_constraints"`
LastSeen time.Time `json:"last_seen"`
}
Device in an application
func (*Device) Delete #
func (d *Device) Delete() error
Delete the device. This function panics if this is a new device.
func (*Device) IsNew #
func (d *Device) IsNew() bool
IsNew indicates whether the device is new.
func (*Device) Personalize #
func (d *Device) Personalize(nwkSKey types.NwkSKey, appSKey types.AppSKey) error
Personalize a device by requesting a DevAddr from the network, and setting the NwkSKey and AppSKey to the given values. This function panics if this is a new device, so make sure you Get() the device first.
func (*Device) PersonalizeFunc #
func (d *Device) PersonalizeFunc(personalizeFunc func(types.DevAddr) (types.NwkSKey, types.AppSKey)) error
PersonalizeFunc personalizes a device by requesting a DevAddr from the network, and setting the NwkSKey and AppSKey to the result of the personalizeFunc. This function panics if this is a new device, so make sure you Get() the device first.
func (*Device) PersonalizeRandom #
func (d *Device) PersonalizeRandom() error
PersonalizeRandom personalizes a device by requesting a DevAddr from the network, and setting the NwkSKey and AppSKey to randomly generated values. This function panics if this is a new device, so make sure you Get() the device first.
func (*Device) SetManager #
func (d *Device) SetManager(manager DeviceManager)
SetManager sets the manager of the device. This function panics if this is not a new device.
func (*Device) Update #
func (d *Device) Update() error
Update the device. This function panics if this is a new device.
type DeviceList #
type DeviceList []*SparseDevice
DeviceList is a slice of *SparseDevice.
func (DeviceList) AsDevices #
func (d DeviceList) AsDevices() []*Device
AsDevices returns the DeviceList as a slice of *Device instead of *SparseDevice
type DeviceManager #
type DeviceManager interface {
// List devices in an application. Use the limit and offset for pagination. Requests that fetch many devices will be
// very slow, which is often not necessary. If you use this function too often, the response will be cached by the
// server, and you might receive outdated data.
List(limit, offset uint64) (DeviceList, error)
// Get details for a device
Get(devID string) (*Device, error)
// Create or Update a device.
Set(*Device) error
// Delete a device
Delete(devID string) error
}
DeviceManager manages devices within an application
type DevicePub #
type DevicePub interface {
Publish(*types.DownlinkMessage) error
}
DevicePub interface for publishing downlink messages to the device
type DevicePubSub #
type DevicePubSub interface {
DevicePub
DeviceSub
}
DevicePubSub combines the DevicePub and DeviceSub interfaces
type DeviceSub #
type DeviceSub interface {
SubscribeUplink() (<-chan *types.UplinkMessage, error)
UnsubscribeUplink() error
SubscribeEvents() (<-chan *types.DeviceEvent, error)
UnsubscribeEvents() error
SubscribeActivations() (<-chan *types.Activation, error)
UnsubscribeActivations() error
Close()
}
DeviceSub interface for subscribing to uplink messages and events from the device
type Simulator #
type Simulator interface {
Uplink(port uint8, payload []byte) error
}
Simulator simulates messages for devices
type SparseDevice #
type SparseDevice struct {
AppID string `json:"app_id"`
DevID string `json:"dev_id"`
AppEUI types.AppEUI `json:"app_eui"`
DevEUI types.DevEUI `json:"dev_eui"`
Description string `json:"description,omitempty"`
DevAddr *types.DevAddr `json:"dev_addr,omitempty"`
NwkSKey *types.NwkSKey `json:"nwk_s_key,omitempty"`
AppSKey *types.AppSKey `json:"app_s_key,omitempty"`
AppKey *types.AppKey `json:"app_key,omitempty"`
Latitude float32 `json:"latitude,omitempty"`
Longitude float32 `json:"longitude,omitempty"`
Altitude int32 `json:"altitude,omitempty"`
Attributes map[string]string `json:"attributes,omitempty"`
}
SparseDevice contains most, but not all fields of the device. It’s returned by List operations to save server resources
func (*SparseDevice) AsDevice #
func (d *SparseDevice) AsDevice() *Device
AsDevice wraps the *SparseDevice and returns a *Device containing that sparse device