device

Documentation

Index

• Constants
• type AggregateMessage
• type Device
  • func NewDevice(deviceID, realm, credentialsSecret, pairingBaseURL string) (*Device, error)
  • func NewDeviceWithOptions(deviceID, realm, credentialsSecret, pairingBaseURL string, opts DeviceOptions) (*Device, error)
  • func NewDeviceWithPersistency(deviceID, realm, credentialsSecret, pairingBaseURL, persistencyDir string) (*Device, error)
  • func (d *Device) AddInterface(astarteInterface interfaces.AstarteInterface) error
  • func (d *Device) ClearCrypto() error
  • func (d *Device) Connect(result chan<- error)
  • func (d *Device) Disconnect(result chan<- error)
  • func (d *Device) GetAllProperties() (map[string]map[string]interface{}, error)
  • func (d *Device) GetAllPropertiesForInterface(interfaceName string) (map[string]interface{}, error)
  • func (d *Device) GetProperty(interfaceName, interfacePath string) (interface{}, error)
  • func (d *Device) IsConnected() bool
  • func (d *Device) RemoveInterface(astarteInterface interfaces.AstarteInterface)
  • func (d *Device) SendAggregateMessage(interfaceName, interfacePath string, values map[string]interface{}) error
  • func (d *Device) SendAggregateMessageWithTimestamp(interfaceName, interfacePath string, values map[string]interface{}, ...) error
  • func (d *Device) SendIndividualMessage(interfaceName, path string, value interface{}) error
  • func (d *Device) SendIndividualMessageWithTimestamp(interfaceName, interfacePath string, value interface{}, timestamp time.Time) error
  • func (d *Device) SetProperty(interfaceName, path string, value interface{}) error
  • func (d *Device) UnsetProperty(interfaceName, path string) error
• type DeviceOptions
  • func NewDeviceOptions() DeviceOptions
• type IndividualMessage

Constants

const (
	DefaultInitialConnectionAttempts = 10
)

Types

type AggregateMessage

type AggregateMessage struct {
	Interface interfaces.AstarteInterface
	Path      string
	Values    map[string]interface{}
	Timestamp time.Time
}

AggregateMessage represents a message for an Interface of aggregation type object

type Device

type Device struct {
	OnIndividualMessageReceived func(*Device, IndividualMessage)
	OnAggregateMessageReceived  func(*Device, AggregateMessage)
	OnErrors                    func(*Device, error)
	OnConnectionStateChanged    func(*Device, bool)
	// contains filtered or unexported fields
}

Device is the base struct for Astarte Devices

func NewDevice

func NewDevice(deviceID, realm, credentialsSecret, pairingBaseURL string) (*Device, error)

NewDevice creates a new Device without persistency. NOTE: This constructor is NOT safe to use in production, as all persistency is turned off. When doing so, a number of features won't be available. Please use NewDeviceWithPersistency or NewDeviceWithOptions instead.

Deprecated: due to its ambiguousness, this constructor will be removed or changed in the future.

func NewDeviceWithOptions

func NewDeviceWithOptions(deviceID, realm, credentialsSecret, pairingBaseURL string, opts DeviceOptions) (*Device, error)

NewDeviceWithOptions creates a new Device with a set of options. It is meant to be used in those cases where NewDeviceWithPersistency doesn't provide you with a satisfactory configuration. Please refer to DeviceOptions documentation for all details. NewDeviceWithOptions will also return an error and will fail if the provided options are invalid or incompatible (e.g.: when requiring a default database without a persistency directory). If you are unsure about what some of these options mean, it is advised to stick to NewDeviceWithPersistency.

func NewDeviceWithPersistency

func NewDeviceWithPersistency(deviceID, realm, credentialsSecret, pairingBaseURL, persistencyDir string) (*Device, error)

NewDeviceWithPersistency creates a new Device with a known persistency directory and an SQLite database which will be created and stored within that directory. It sticks to sane defaults and it is the right choice in most cases. Please note that when creating a device like this, you must compile your executable with CGO enabled due to SQLite requirements. More advanced configuration can be provided when creating a device with NewDeviceWithOptions.

func (*Device) AddInterface

func (d *Device) AddInterface(astarteInterface interfaces.AstarteInterface) error

AddInterface adds an interface to the device. The interface must be loaded with ParseInterface from the astarte-go/interfaces package, which also ensures that the interface is valid. The return value should be ignored as the error is always `nil` (i.e. AddInterface cannot fail). TODO since the function always returns nil, do not return an error (target release 1.0)

func (*Device) ClearCrypto

func (d *Device) ClearCrypto() error

ClearCrypto clears all the temporary crypto files of the Device. Usually, you shouldn't need to call this function.

func (*Device) Connect

func (d *Device) Connect(result chan<- error)

Connect connects the device through a goroutine nolint

func (*Device) Disconnect

func (d *Device) Disconnect(result chan<- error)

Disconnect disconnects the device

func (*Device) GetAllProperties

func (d *Device) GetAllProperties() (map[string]map[string]interface{}, error)

GetAllProperties retrieves all available and stored properties from the local storage, if any. It returns an empty map and an error in case no storage is available or if any error happened while retrieving the properties, otherwise it returns a multi-dimensional map containing all the available interfaces, and for each interface all its available paths with their respective values.

func (*Device) GetAllPropertiesForInterface

func (d *Device) GetAllPropertiesForInterface(interfaceName string) (map[string]interface{}, error)

GetAllPropertiesForInterface retrieves all available and stored properties from the local storage, if any, for a given interface. It returns an empty map and an error in case no storage is available, if no properties were found or if any error happened while handling them, otherwise it returns a map containing all stored paths and their respective values.

func (*Device) GetProperty

func (d *Device) GetProperty(interfaceName, interfacePath string) (interface{}, error)

GetProperty retrieves a property from the local storage, if any. It returns nil and an error in case no storage is available or if the property wasn't found in the local storage or if any other error occurred while handling it, otherwise it returns the property's value.

func (*Device) IsConnected

func (d *Device) IsConnected() bool

IsConnected returns whether the device is connected or not

func (*Device) RemoveInterface

func (d *Device) RemoveInterface(astarteInterface interfaces.AstarteInterface)

RemoveInterface removes an interface from the device

func (*Device) SendAggregateMessage

func (d *Device) SendAggregateMessage(interfaceName, interfacePath string, values map[string]interface{}) error

SendAggregateMessage adds to the publishing channel a new message towards an Object Aggregated interface. values must be a map containing the last tip of the endpoint, with no slash, as the key, and the corresponding value as value. interfacePath should match the path of the base endpoint, without the last tip. This call can be blocking if the channel is full (see `MaxInflightMessages`). Example: if dealing with an aggregate interface with endpoints [/my/aggregate/firstValue, /my/aggregate/secondValue], interfacePath would be "/my/aggregate", and values would be map["firstValue": <value>, "secondValue": <value>]

func (*Device) SendAggregateMessageWithTimestamp

func (d *Device) SendAggregateMessageWithTimestamp(interfaceName, interfacePath string, values map[string]interface{}, timestamp time.Time) error

SendAggregateMessageWithTimestamp adds to the publishing channel a new message towards an Object Aggregated interface, with explicit timestamp. values must be a map containing the last tip of the endpoint, with no slash, as the key, and the corresponding value as value. interfacePath should match the path of the base endpoint, without the last tip. This call can be blocking if the channel is full (see `MaxInflightMessages`). Example: if dealing with an aggregate interface with endpoints [/my/aggregate/firstValue, /my/aggregate/secondValue], interfacePath would be "/my/aggregate", and values would be map["firstValue": <value>, "secondValue": <value>]

func (*Device) SendIndividualMessage

func (d *Device) SendIndividualMessage(interfaceName, path string, value interface{}) error

SendIndividualMessage adds to the publishing channel a new message towards an individual aggregation interface. This call can be blocking if the channel is full (see `MaxInflightMessages`).

func (*Device) SendIndividualMessageWithTimestamp

func (d *Device) SendIndividualMessageWithTimestamp(interfaceName, interfacePath string, value interface{}, timestamp time.Time) error

SendIndividualMessageWithTimestamp adds to the publishing channel a new message towards an individual aggregation interface, with explicit timestamp. This call can be blocking if the channel is full (see `MaxInflightMessages`).

func (*Device) SetProperty

func (d *Device) SetProperty(interfaceName, path string, value interface{}) error

SetProperty sets a property in Astarte. It adds to the publishing channel a property set message that is equivalent to `SendIndividualMessage` in every regard, except this call will fail if the interface isn't a property interface. It is advised to use this call, as APIs might change in the future. Once the property is set, it is also added to the local cache and can be retrieved at any time using `GetProperty` or `GetAllProperties`. This call can be blocking if the channel is full (see `MaxInflightMessages`).

func (*Device) UnsetProperty

func (d *Device) UnsetProperty(interfaceName, path string) error

UnsetProperty deletes an existing property from Astarte, if the property can be unset. It adds to the publishing channel a property deletion message that contains the interface name and the path to be deleted. Once the property is deleted, it is also removed from the local cache. This call can be blocking if the channel is full (see `MaxInflightMessages`).

type DeviceOptions

type DeviceOptions struct {
	// MaxInflightMessages is the maximum number of messages that can be in publishing channel at any given time
	// before adding messages becomes blocking.
	MaxInflightMessages int

	// IgnoreSSLErrors allows the device to ignore client SSL errors during connection.
	// Useful if you're using the device to connect to a test instance of Astarte with self signed certificates,
	// it is not recommended to leave this to true in production.
	IgnoreSSLErrors bool

	// AutoReconnect sets whether the device should reconnect automatically if it loses the connection
	// after establishing it.
	AutoReconnect bool

	// ConnectRetry sets whether the device should retry to connect if the first connection
	// fails. Defaults to false.
	ConnectRetry bool

	// MaxRetries sets the number of attempts for the device to establish the first connection.
	// If ConnectRetry is false, MaxRetries will be ignored.
	MaxRetries int

	// RootCAs, when not nil, sets a custom set of Root CAs to trust against the broker
	RootCAs *x509.CertPool

	// UseMqttStore defines whether the SDK will use a store or not for the underlying
	// MQTT client. It will use the PersistencyDir when it is activated.
	UseMqttStore bool

	// PersistencyDir is a known path that will be used by the SDK for MQTT
	// persistency, for the default database if used, and for crypto storage unless
	// CryptoDir is specified.
	// If none of them are specified, the persistency dir can be empty. Otherwise,
	// an error will be returned upon creation.
	//
	// Creating a Device without persistency is not recommended and should be done only
	// when aware of the implications. Please read all documentation for details.
	PersistencyDir string

	// CryptoDir is a known, available path that will be used by the SDK for storing
	// certificate and private key for connecting to Astarte. When not specified, it
	// will use the PersistencyDir if specified, or a temporary directory if no persistency
	// was enabled. Please keep in mind that if a temporary directory is used for crypto
	// storage, certificates and private keys will always be regenerated at each startup,
	// which will take a toll on performances and startup times.
	CryptoDir string

	// UseDatabase defines whether the SDK should use a database for properties
	// and datastream persistency. It will be stored in the specified PersistencyDir.
	// When set to true, and no database is provided, the default database (SQLite) will
	// be used.
	UseDatabase bool

	// Database is a pointer to a valid, open gorm DB to be used for persistency, provided
	// UseDatabase is true. Ensure you're passing a dedicated DB which
	// can be used exclusively by the Astarte SDK to prevent naming conflicts.
	// If both this variable is nil and UseDatabase is false, no database will be used.
	// Not using a database when you can rely on persistency is strongly discouraged - however,
	// there might be cases in which such a thing is needed, for example if you cannot use CGO
	// when compiling your executable.
	Database *gorm.DB
}

DeviceOptions define a set of configurable options for a Device.

func NewDeviceOptions

func NewDeviceOptions() DeviceOptions

NewDeviceOptions will create a new DeviceOptions with some sensible default values.

type IndividualMessage

type IndividualMessage struct {
	Interface interfaces.AstarteInterface
	Path      string
	Value     interface{}
	Timestamp time.Time
}

IndividualMessage represents a message for an Interface of aggregation type individual