nbiot

package module
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 23, 2020 License: Apache-2.0 Imports: 12 Imported by: 5

README

nbiot-go

GoDoc Travis-CI

NBIoT-Go provides a Go client for the REST API for Telenor NB-IoT.

Important note

Version 2.1.1 of the service at nbiot.engineering introduces a breaking change for the go client library. Versions prior to 2.1.1 won't work with v0.6.0 of this library.

Configuration

The configuration file is usually located at ${HOME}/.telenor-nbiot, but the library will start at the current directory and scan each parent directory until it finds a config file. The file is a simple list of key/value pairs. Additional values are ignored. Comments must start with a #:

#
# This is the URL of the Telenor NB-IoT REST API. The default value is
# https://api.nbiot.telenor.io and can usually be omitted.
address=https://api.nbiot.telenor.io

#
# This is the API token. Create new token by logging in to the Telenor NB-IoT
# front-end at https://nbiot.engineering and create a new token there.
token=<your api token goes here>

The configuration file settings can be overridden by setting the environment variables TELENOR_NBIOT_ADDRESS and TELENOR_NBIOT_TOKEN. If you only use environment variables the configuration file can be ignored.

Use the NewWithAddr function to bypass the default configuration file and environment variables when you want to configure the client programmatically.

Updating resources

The various Client.Update* methods work via HTTP PATCH, which means they will only modify or set fields, not delete them. There are special Client.Delete*Tag methods for deleting tags.

Example

package main

import (
	"io"
	"log"

	"github.com/telenordigital/nbiot-go"
)

func main() {
	client, err := nbiot.New()
	if err != nil {
		log.Fatal("Error creating client:", err)
	}

	collection, err := client.CreateCollection(nbiot.Collection{
		Tags: map[string]string{
			"name": "example collection",
		},
	})
	if err != nil {
		log.Fatal("Error creating collection: ", err)
	}

	device, err := client.CreateDevice(collection.ID, nbiot.Device{
		IMSI: "0345892703458",
		IMEI: "1487252347803",
		Tags: map[string]string{
			"name": "example device",
		},
	})
	if err != nil {
		log.Fatal("Error creating device: ", err)
	}

	stream, err := client.DeviceOutputStream(collection.ID, device.ID)
	if err != nil {
		log.Fatal("Error creating stream: ", err)
	}
	defer stream.Close()

	for {
		data, err := stream.Recv()
		if err == io.EOF {
			break
		}
		if err != nil {
			log.Fatal("Error receiving data: ", err)
		}

		log.Print("received payload: ", data.Payload)
	}
}

Documentation

Overview

Package nbiot-go provides a client for the REST API for Telenor NB-IoT.

All Create* and Update* methods return the created and updated entity, respectively, which may include setting or updating fields.

Index

Constants

View Source 
const (
	// DefaultAddr is the default address of the Telenor NB-IoT API. You normally won't
	// have to change this.
	DefaultAddr = "https://api.nbiot.telenor.io"

	// ConfigFile is the name for the config file. The configuration file is a
	// plain text file that contains the Telenor NB-IoT configuration.
	// The configuration file is expected to be in the current home directory
	// and contain a "address=<value>" line and/or a "token=<value>" line.
	ConfigFile = ".telenor-nbiot"

	// AddressEnvironmentVariable is the name of the environment variable that
	// can be used to override the address set in the configuration file.
	// If the  environment variable isn't set (or is empty) the configuration
	// file settings will be used.
	AddressEnvironmentVariable = "TELENOR_NBIOT_ADDRESS"

	// TokenEnvironmentVariable is the name of the environment variable that
	// can be used to override the token set in the configuration file.
	TokenEnvironmentVariable = "TELENOR_NBIOT_TOKEN"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type BroadcastError 

type BroadcastError struct {
	DeviceID string `json:"deviceId"`
	Message  string `json:"message"`
}

BroadcastError is an error from a broadcast.

type BroadcastResult 

type BroadcastResult struct {
	Sent   int              `json:"sent"`
	Failed int              `json:"failed"`
	Errors []BroadcastError `json:"errors"`
}

BroadcastResult is the result of a broadcast.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a client for Telenor NB-IoT.

func New 

func New() (*Client, error)

New creates a new client with the default configuration. The default configuration can be specified in a configuration file or through environment variables.

func NewWithAddr 

func NewWithAddr(addr, token string) (*Client, error)

NewWithAddr creates a new client with the specified address and token.

func (*Client) AcceptInvite 

func (c *Client) AcceptInvite(code string) (t Team, err error)

AcceptInvite accepts a invite.

func (*Client) Address 

func (c *Client) Address() string

Address returns the client's address.

func (*Client) Broadcast 

func (c *Client) Broadcast(collectionID string, msg DownstreamMessage) (result BroadcastResult, err error)

Broadcast sends a message to all devices in a collection.

func (*Client) Collection 

func (c *Client) Collection(id string) (Collection, error)

Collection gets a collection.

func (*Client) CollectionData 

func (c *Client) CollectionData(collectionID string, since time.Time, until time.Time, limit int) ([]OutputDataMessage, error)

CollectionData returns all the stored data for the collection.

func (*Client) CollectionOutputStream 

func (c *Client) CollectionOutputStream(collectionID string) (*OutputStream, error)

CollectionOutputStream streams messages from all devices in a collection.

func (*Client) Collections 

func (c *Client) Collections() ([]Collection, error)

Collections gets all collections that the user has access to.

func (*Client) CreateCollection 

func (c *Client) CreateCollection(collection Collection) (Collection, error)

CreateCollection creates a collection.

func (*Client) CreateDevice 

func (c *Client) CreateDevice(collectionID string, device Device) (Device, error)

CreateDevice creates a device.

func (*Client) CreateInvite 

func (c *Client) CreateInvite(teamID string) (Invite, error)

CreateInvite creates a invite.

func (*Client) CreateOutput 

func (c *Client) CreateOutput(collectionID string, output Output) (Output, error)

CreateOutput creates an output

func (*Client) CreateTeam 

func (c *Client) CreateTeam(team Team) (Team, error)

CreateTeam creates a team.

func (*Client) DeleteCollection 

func (c *Client) DeleteCollection(id string) error

DeleteCollection deletes a collection.

func (*Client) DeleteCollectionTag 

func (c *Client) DeleteCollectionTag(id, name string) error

DeleteCollectionTag deletes a tag from a collection.

func (*Client) DeleteDevice 

func (c *Client) DeleteDevice(collectionID, deviceID string) error

DeleteDevice deletes a device.

func (*Client) DeleteDeviceTag 

func (c *Client) DeleteDeviceTag(collectionID, deviceID, name string) error

DeleteDeviceTag deletes a tag from a device.

func (*Client) DeleteInvite 

func (c *Client) DeleteInvite(teamID, code string) error

DeleteInvite deletes an invite.

func (*Client) DeleteOutput 

func (c *Client) DeleteOutput(collectionID, outputID string) error

DeleteOutput removes an output

func (*Client) DeleteOutputTag 

func (c *Client) DeleteOutputTag(collectionID, outputID, name string) error

DeleteOutputTag deletes a tag from an output.

func (*Client) DeleteTeam 

func (c *Client) DeleteTeam(id string) error

DeleteTeam deletes a team.

func (*Client) DeleteTeamMember 

func (c *Client) DeleteTeamMember(teamID, userID string) error

DeleteTeamMember deletes a team member.

func (*Client) DeleteTeamTag 

func (c *Client) DeleteTeamTag(id, name string) error

DeleteTeamTag deletes a tag from a team.

func (*Client) Device 

func (c *Client) Device(collectionID, deviceID string) (Device, error)

Device gets a device.

func (*Client) DeviceData 

func (c *Client) DeviceData(collectionID, deviceID string, since time.Time, until time.Time, limit int) ([]OutputDataMessage, error)

DeviceData returns all the stored data for the device.

func (*Client) DeviceOutputStream 

func (c *Client) DeviceOutputStream(collectionID, deviceID string) (*OutputStream, error)

DeviceOutputStream streams messages from one device.

func (*Client) Devices 

func (c *Client) Devices(collectionID string) ([]Device, error)

Devices gets all devices in the collection.

func (*Client) Invite 

func (c *Client) Invite(teamID, code string) (Invite, error)

Invite gets an invite.

func (*Client) Invites 

func (c *Client) Invites(teamID string) ([]Invite, error)

Invites gets all invites for the team.

func (*Client) Output 

func (c *Client) Output(collectionID, outputID string) (Output, error)

Output retrieves an output

func (*Client) OutputLogs 

func (c *Client) OutputLogs(collectionID, outputID string) ([]OutputLogEntry, error)

OutputLogs returns the logs for an output.

func (*Client) OutputStatus 

func (c *Client) OutputStatus(collectionID, outputID string) (stat OutputStatus, err error)

OutputStatus returns the status for an output.

func (*Client) Outputs 

func (c *Client) Outputs(collectionID string) ([]Output, error)

Outputs retrieves a list of outputs on a collection

func (*Client) Send 

func (c *Client) Send(collectionID, deviceID string, msg DownstreamMessage) error

Send sends a message to a device.

func (*Client) SystemDefaults 

func (c *Client) SystemDefaults() (SystemDefaults, error)

SystemDefaults returns the system defaults.

func (*Client) Team 

func (c *Client) Team(id string) (Team, error)

Team gets a team.

func (*Client) Teams 

func (c *Client) Teams() ([]Team, error)

Teams gets all teams that the user belongs to.

func (*Client) UpdateCollection 

func (c *Client) UpdateCollection(collection Collection) (Collection, error)

UpdateCollection updates a collection. No tags are deleted, only added or updated.

func (*Client) UpdateDevice 

func (c *Client) UpdateDevice(collectionID string, device Device) (Device, error)

UpdateDevice updates a device. No tags are deleted, only added or updated.

func (*Client) UpdateOutput 

func (c *Client) UpdateOutput(collectionID string, output Output) (Output, error)

UpdateOutput updates an output. The type field can't be modified No tags are deleted, only added or updated.

func (*Client) UpdateTeam 

func (c *Client) UpdateTeam(team Team) (Team, error)

UpdateTeam updates a team, but not its members. No tags are deleted, only added or updated.

func (*Client) UpdateTeamMemberRole 

func (c *Client) UpdateTeamMemberRole(teamID, userID, role string) (Member, error)

UpdateTeamMemberRole updates the role of a team member.

type ClientError 

type ClientError struct {
	HTTPStatusCode int
	Message        string
}

ClientError describes what went wrong with a request that otherwise succeeded but which resulted in an HTTP status code >= 300.

func (ClientError) Error 

func (e ClientError) Error() string

type Collection 

type Collection struct {
	ID        string            `json:"collectionId"`
	TeamID    string            `json:"teamId,omitempty"`
	FieldMask *FieldMask        `json:"fieldMask,omitempty"`
	Tags      map[string]string `json:"tags,omitempty"`
}

Collection represents a collection.

type Device 

type Device struct {
	ID           string            `json:"deviceId"`
	CollectionID string            `json:"collectionId,omitempty"`
	IMEI         string            `json:"imei,omitempty"`
	IMSI         string            `json:"imsi,omitempty"`
	Tags         map[string]string `json:"tags,omitempty"`
}

Device represents a device.

type DownstreamMessage 

type DownstreamMessage struct {
	Port      int    `json:"port"`
	Payload   []byte `json:"payload"`
	Path      string `json:"coapPath,omitempty"`  // This is used by CoAP support to specify the path
	Transport string `json:"transport,omitempty"` // This is used by CoAP support to specify transport
}

DownstreamMessage is a message to be sent to a device.

type FieldMask 

type FieldMask struct {
	IMSI     *bool `json:"imsi"`
	IMEI     *bool `json:"imei"`
	Location *bool `json:"location"`
	MSISDN   *bool `json:"msisdn"`
}

FieldMask indicates which fields will be masked from API responses.

type IFTTTOutput 

type IFTTTOutput struct {
	ID           string
	CollectionID string
	Key          string
	EventName    string
	AsIsPayload  bool
	Disabled     bool
	Tags         map[string]string
}

IFTTTOutput describes an IFTTT output.

func (IFTTTOutput) GetCollectionID 

func (o IFTTTOutput) GetCollectionID() string

GetCollectionID returns the collection ID.

func (IFTTTOutput) GetID 

func (o IFTTTOutput) GetID() string

GetID returns the output ID.

func (IFTTTOutput) GetTags 

func (o IFTTTOutput) GetTags() map[string]string

GetTags returns the output's tags.

func (IFTTTOutput) IsDisabled 

func (o IFTTTOutput) IsDisabled() bool

IsDisabled returns whether the output is disabled.

type Invite 

type Invite struct {
	Code      string `json:"code"`
	CreatedAt int    `json:"createdAt"` // time stamp (in ms)
}

Invite is an invitation to a team.

type MQTTOutput 

type MQTTOutput struct {
	ID               string
	CollectionID     string
	Endpoint         string
	DisableCertCheck bool
	Username         string
	Password         string
	ClientID         string
	TopicName        string
	Disabled         bool
	Tags             map[string]string
}

MQTTOutput describes an MQTT output.

func (MQTTOutput) GetCollectionID 

func (o MQTTOutput) GetCollectionID() string

GetCollectionID returns the collection ID.

func (MQTTOutput) GetID 

func (o MQTTOutput) GetID() string

GetID returns the output ID.

func (MQTTOutput) GetTags 

func (o MQTTOutput) GetTags() map[string]string

GetTags returns the output's tags.

func (MQTTOutput) IsDisabled 

func (o MQTTOutput) IsDisabled() bool

IsDisabled returns whether the output is disabled.

type Member 

type Member struct {
	UserID        string `json:"userId"`
	Role          string `json:"role"`
	Name          string `json:"name,omitempty"`
	Email         string `json:"email,omitempty"`
	Phone         string `json:"phone,omitempty"`
	VerifiedEmail bool   `json:"verifiedEmail"`
	VerifiedPhone bool   `json:"verifiedPhone"`
	ConnectID     string `json:"connectId,omitempty"`
	GitHubLogin   string `json:"gitHubLogin,omitempty"`
	AuthType      string `json:"authType,omitempty"`
	AvatarURL     string `json:"avatarUrl,omitempty"`
}

Member is a member of a team.

type Output 

type Output interface {
	GetID() string
	GetCollectionID() string
	IsDisabled() bool
	GetTags() map[string]string
	// contains filtered or unexported methods
}

Output represents a data output for a collection. WebHookOutput, MQTTOutput, IFTTTOutput, and UDPOutput implement this interface.

type OutputDataMessage 

type OutputDataMessage struct {
	Device       Device `json:"device"`
	Payload      []byte `json:"payload"`
	Received     int64  `json:"received,string"`
	Transport    string `json:"transport"`
	CoAPMetaData struct {
		Method string `json:"method"`
		Path   string `json:"path"`
	} `json:"coapMetaData"`
	UDPMetaData struct {
		LocalPort  int `json:"localPort"`
		RemotePort int `json:"remotePort"`
	} `json:"udpMetaData"`
}

OutputDataMessage represents a message sent by a device.

type OutputLogEntry 

type OutputLogEntry struct {
	Message   string `json:"message"`   // The message itself
	Timestamp int64  `json:"timestamp"` // Time in ms
	Repeated  uint8  `json:"repeated"`  // Repeat count
}

OutputLogEntry is an entry in an output log.

type OutputStatus 

type OutputStatus struct {
	ErrorCount int `json:"errorCount"`
	Forwarded  int `json:"forwarded"`
	Received   int `json:"received"`
	Retries    int `json:"retries"`
}

OutputStatus is the status of an output.

type OutputStream 

type OutputStream struct {
	// contains filtered or unexported fields
}

OutputStream provides a stream of OutputDataMessages.

func (*OutputStream) Close 

func (s *OutputStream) Close()

Close closes the output stream.

func (*OutputStream) Recv 

func (s *OutputStream) Recv() (OutputDataMessage, error)

Recv blocks until a new message is received. It returns io.EOF if the stream is closed by the server.

type SystemDefaults 

type SystemDefaults struct {
	DefaultFieldMask *FieldMask `json:"defaultFieldMask,omitempty"`
	ForcedFieldMask  *FieldMask `json:"forcedFieldMask,omitempty"`
}

SystemDefaults is the system defaults.

type Team 

type Team struct {
	ID      string            `json:"teamId"`
	Members []Member          `json:"members,omitempty"`
	Tags    map[string]string `json:"tags,omitempty"`
}

Team represents a team.

type UDPOutput 

type UDPOutput struct {
	ID           string
	CollectionID string
	Host         string
	Port         int
	Disabled     bool
	Tags         map[string]string
}

UDPOutput describes a UDP output.

func (UDPOutput) GetCollectionID 

func (o UDPOutput) GetCollectionID() string

GetCollectionID returns the collection ID.

func (UDPOutput) GetID 

func (o UDPOutput) GetID() string

GetID returns the output ID.

func (UDPOutput) GetTags 

func (o UDPOutput) GetTags() map[string]string

GetTags returns the output's tags.

func (UDPOutput) IsDisabled 

func (o UDPOutput) IsDisabled() bool

IsDisabled returns whether the output is disabled.

type WebHookOutput 

type WebHookOutput struct {
	ID                string
	CollectionID      string
	URL               string
	BasicAuthUser     string
	BasicAuthPass     string
	CustomHeaderName  string
	CustomHeaderValue string
	Disabled          bool
	Tags              map[string]string
}

WebHookOutput describes a webhook output.

func (WebHookOutput) GetCollectionID 

func (o WebHookOutput) GetCollectionID() string

GetCollectionID returns the collection ID.

func (WebHookOutput) GetID 

func (o WebHookOutput) GetID() string

GetID returns the output ID.

func (WebHookOutput) GetTags 

func (o WebHookOutput) GetTags() map[string]string

GetTags returns the output's tags.

func (WebHookOutput) IsDisabled 

func (o WebHookOutput) IsDisabled() bool

IsDisabled returns whether the output is disabled.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.