sdk

README

Mainflux Go SDK

Go SDK, a Go driver for Mainflux HTTP API.

Does both system administration (provisioning) and messaging.

Installation

Import "gitee.com/shtemmi/iotflux/sdk/go" in your Go package.

import "gitee.com/shtemmi/iotflux/pkg/sdk/go"```

Then call SDK Go functions to interact with the system.

## API Reference

```go
FUNCTIONS

func NewMfxSDK(host, port string, tls bool) *MfxSDK

func (sdk *MfxSDK) Channel(id, token string) (things.Channel, error)
    Channel - gets channel by ID

func (sdk *MfxSDK) Channels(token string) ([]things.Channel, error)
    Channels - gets all channels

func (sdk *MfxSDK) Connect(struct{[]string, []string}, token string) error
    Connect - connect things to channels

func (sdk *MfxSDK) CreateChannel(data, token string) (string, error)
    CreateChannel - creates new channel and generates UUID

func (sdk *MfxSDK) CreateThing(data, token string) (string, error)
    CreateThing - creates new thing and generates thing UUID

func (sdk *MfxSDK) CreateToken(user, pwd string) (string, error)
    CreateToken - create user token

func (sdk *MfxSDK) CreateUser(user, pwd string) error
    CreateUser - create user

func (sdk *MfxSDK) User(pwd string) (user, error)
    User - gets user

func (sdk *MfxSDK) UpdateUser(user, pwd string) error
    UpdateUser - update user

func (sdk *MfxSDK) UpdatePassword(user, pwd string) error
    UpdatePassword - update user password

func (sdk *MfxSDK) DeleteChannel(id, token string) error
    DeleteChannel - removes channel

func (sdk *MfxSDK) DeleteThing(id, token string) error
    DeleteThing - removes thing

func (sdk *MfxSDK) DisconnectThing(thingID, chanID, token string) error
    DisconnectThing - connect thing to a channel

func (sdk mfSDK) SendMessage(chanID, msg, token string) error
    SendMessage - send message on Mainflux channel

func (sdk mfSDK) SetContentType(ct ContentType) error
    SetContentType - set message content type. Available options are SenML
    JSON, custom JSON and custom binary (octet-stream).

func (sdk mfSDK) Thing(id, token string) (Thing, error)
    Thing - gets thing by ID

func (sdk mfSDK) Things(token string) ([]Thing, error)
    Things - gets all things

func (sdk mfSDK) UpdateChannel(channel Channel, token string) error
    UpdateChannel - update a channel

func (sdk mfSDK) UpdateThing(thing Thing, token string) error
    UpdateThing - updates thing by ID

func (sdk mfSDK) Version() (string, error)
    Version - server health check

Documentation

Index

• Variables
• type BootstrapConfig
• type Cert
• type Channel
• type ChannelsPage
• type Config
• type ConfigUpdateCertReq
• type ConnectionIDs
• type ContentType
• type Group
• type GroupsPage
• type MessagesPage
• type SDK
  • func NewSDK(conf Config) SDK
• type Thing
• type ThingsPage
• type User
• type UserPasswordReq
• type UsersPage

Variables

var (
	// ErrUnauthorized indicates that entity creation failed.
	ErrUnauthorized = errors.New("unauthorized, missing credentials")

	// ErrFailedCreation indicates that entity creation failed.
	ErrFailedCreation = errors.New("failed to create entity")

	// ErrFailedUpdate indicates that entity update failed.
	ErrFailedUpdate = errors.New("failed to update entity")

	// ErrFailedFetch indicates that fetching of entity data failed.
	ErrFailedFetch = errors.New("failed to fetch entity")

	// ErrFailedRemoval indicates that entity removal failed.
	ErrFailedRemoval = errors.New("failed to remove entity")

	// ErrFailedConnect indicates that connecting thing to channel failed.
	ErrFailedConnect = errors.New("failed to connect thing to channel")

	// ErrFailedDisconnect indicates that disconnecting thing from a channel failed.
	ErrFailedDisconnect = errors.New("failed to disconnect thing from channel")

	// ErrFailedPublish indicates that publishing message failed.
	ErrFailedPublish = errors.New("failed to publish message")

	// ErrFailedRead indicates that read messages failed.
	ErrFailedRead = errors.New("failed to read messages")

	// ErrInvalidContentType indicates that non-existent message content type
	// was passed.
	ErrInvalidContentType = errors.New("Unknown Content Type")

	// ErrFetchVersion indicates that fetching of version failed.
	ErrFetchVersion = errors.New("failed to fetch version")

	// ErrFailedWhitelist failed to whitelist configs
	ErrFailedWhitelist = errors.New("failed to whitelist")

	// ErrCerts indicates error fetching certificates.
	ErrCerts = errors.New("failed to fetch certs data")

	// ErrCertsRemove indicates failure while cleaning up from the Certs service.
	ErrCertsRemove = errors.New("failed to remove certificate")

	// ErrFailedCertUpdate failed to update certs in bootstrap config
	ErrFailedCertUpdate = errors.New("failed to update certs in bootstrap config")

	// ErrFailedUserAdd failed to add user to a group.
	ErrFailedUserAdd = errors.New("failed to add user to group")
)

Types

type BootstrapConfig

type BootstrapConfig struct {
	ThingID     string    `json:"thing_id,omitempty"`
	Channels    []string  `json:"channels,omitempty"`
	ExternalID  string    `json:"external_id,omitempty"`
	ExternalKey string    `json:"external_key,omitempty"`
	MFThing     string    `json:"mainflux_id,omitempty"`
	MFChannels  []Channel `json:"mainflux_channels,omitempty"`
	MFKey       string    `json:"mainflux_key,omitempty"`
	Name        string    `json:"name,omitempty"`
	ClientCert  string    `json:"client_cert,omitempty"`
	ClientKey   string    `json:"client_key,omitempty"`
	CACert      string    `json:"ca_cert,omitempty"`
	Content     string    `json:"content,omitempty"`
	State       int       `json:"state,omitempty"`
}

BootstrapConfig represents Configuration entity. It wraps information about external entity as well as info about corresponding Mainflux entities. MFThing represents corresponding Mainflux Thing ID. MFKey is key of corresponding Mainflux Thing. MFChannels is a list of Mainflux Channels corresponding Mainflux Thing connects to.

type Cert

type Cert struct {
	CACert     string `json:"issuing_ca,omitempty"`
	ClientKey  string `json:"client_key,omitempty"`
	ClientCert string `json:"client_cert,omitempty"`
}

Cert represents certs data.

type Channel

type Channel struct {
	ID       string                 `json:"id,omitempty"`
	Name     string                 `json:"name,omitempty"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

Channel represents mainflux channel.

type ChannelsPage

type ChannelsPage struct {
	Channels []Channel `json:"channels"`
	// contains filtered or unexported fields
}

ChannelsPage contains list of channels in a page with proper metadata.

type Config

type Config struct {
	BaseURL           string
	ReaderURL         string
	BootstrapURL      string
	CertsURL          string
	ReaderPrefix      string
	UsersPrefix       string
	GroupsPrefix      string
	ThingsPrefix      string
	HTTPAdapterPrefix string
	BootstrapPrefix   string
	MsgContentType    ContentType
	TLSVerification   bool
}

Config contains sdk configuration parameters.

type ConfigUpdateCertReq

type ConfigUpdateCertReq struct {
	ClientCert string `json:"client_cert"`
	ClientKey  string `json:"client_key"`
	CACert     string `json:"ca_cert"`
}

type ConnectionIDs

type ConnectionIDs struct {
	ChannelIDs []string `json:"channel_ids"`
	ThingIDs   []string `json:"thing_ids"`
}

ConnectionIDs contains ID lists of things and channels to be connected

type ContentType

type ContentType string

ContentType represents all possible content types.

const (
	// CTJSON represents JSON content type.
	CTJSON ContentType = "application/json"

	// CTJSONSenML represents JSON SenML content type.
	CTJSONSenML ContentType = "application/senml+json"

	// CTBinary represents binary content type.
	CTBinary ContentType = "application/octet-stream"
)

type Group

type Group struct {
	ID          string                 `json:"id,omitempty"`
	Name        string                 `json:"name,omitempty"`
	Description string                 `json:"description,omitempty"`
	ParentID    string                 `json:"parent_id,omitempty"`
	Metadata    map[string]interface{} `json:"metadata,omitempty"`
}

Group represents mainflux users group.

type GroupsPage

type GroupsPage struct {
	Groups []Group `json:"groups"`
	// contains filtered or unexported fields
}

type MessagesPage

type MessagesPage struct {
	Messages []senml.Message `json:"messages,omitempty"`
	// contains filtered or unexported fields
}

MessagesPage contains list of messages in a page with proper metadata.

type SDK

type SDK interface {
	// CreateUser registers mainflux user.
	CreateUser(user User) (string, error)

	// User returns user object.
	User(token string) (User, error)

	// CreateToken receives credentials and returns user token.
	CreateToken(user User) (string, error)

	// UpdateUser updates existing user.
	UpdateUser(user User, token string) error

	// UpdatePassword updates user password.
	UpdatePassword(oldPass, newPass, token string) error

	// CreateThing registers new thing and returns its id.
	CreateThing(thing Thing, token string) (string, error)

	// CreateThings registers new things and returns their ids.
	CreateThings(things []Thing, token string) ([]Thing, error)

	// Things returns page of things.
	Things(token string, offset, limit uint64, name string) (ThingsPage, error)

	// ThingsByChannel returns page of things that are connected or not connected
	// to specified channel.
	ThingsByChannel(token, chanID string, offset, limit uint64, connected bool) (ThingsPage, error)

	// Thing returns thing object by id.
	Thing(id, token string) (Thing, error)

	// UpdateThing updates existing thing.
	UpdateThing(thing Thing, token string) error

	// DeleteThing removes existing thing.
	DeleteThing(id, token string) error

	// CreateGroup creates new group and returns its id.
	CreateGroup(group Group, token string) (string, error)

	// DeleteGroup deletes users group.
	DeleteGroup(id, token string) error

	// Groups returns page of users groups.
	Groups(token string, offset, limit uint64, name string) (GroupsPage, error)

	// Group returns users group object by id.
	Group(id, token string) (Group, error)

	// Assign assigns user to a group.
	Assign(userID, groupID, token string) error

	// Unassign removes user from a group.
	Unassign(userID, groupID, token string) error

	// Members lists member users of a group.
	Members(groupID, token string, offset, limit uint64) (UsersPage, error)

	// Memberships lists groups for user.
	Memberships(userID, token string, offset, limit uint64) (GroupsPage, error)

	// UpdateGroup updates existing group.
	UpdateGroup(group Group, token string) error

	// Connect bulk connects things to channels specified by id.
	Connect(conns ConnectionIDs, token string) error

	// DisconnectThing disconnect thing from specified channel by id.
	DisconnectThing(thingID, chanID, token string) error

	// CreateChannel creates new channel and returns its id.
	CreateChannel(channel Channel, token string) (string, error)

	// CreateChannels registers new channels and returns their ids.
	CreateChannels(channels []Channel, token string) ([]Channel, error)

	// Channels returns page of channels.
	Channels(token string, offset, limit uint64, name string) (ChannelsPage, error)

	// ChannelsByThing returns page of channels that are connected or not connected
	// to specified thing.
	ChannelsByThing(token, thingID string, offset, limit uint64, connected bool) (ChannelsPage, error)

	// Channel returns channel data by id.
	Channel(id, token string) (Channel, error)

	// UpdateChannel updates existing channel.
	UpdateChannel(channel Channel, token string) error

	// DeleteChannel removes existing channel.
	DeleteChannel(id, token string) error

	// SendMessage send message to specified channel.
	SendMessage(chanID, msg, token string) error

	// ReadMessages read messages of specified channel.
	ReadMessages(chanID, token string) (MessagesPage, error)

	// SetContentType sets message content type.
	SetContentType(ct ContentType) error

	// Version returns used mainflux version.
	Version() (string, error)

	// AddBootstrap add bootstrap configuration
	AddBootstrap(token string, cfg BootstrapConfig) (string, error)

	// View returns Thing Config with given ID belonging to the user identified by the given token.
	ViewBootstrap(token, id string) (BootstrapConfig, error)

	// Update updates editable fields of the provided Config.
	UpdateBootstrap(token string, cfg BootstrapConfig) error

	// Update boostrap config certificates
	UpdateBootstrapCerts(token string, id string, clientCert, clientKey, ca string) error

	// Remove removes Config with specified token that belongs to the user identified by the given token.
	RemoveBootstrap(token, id string) error

	// Bootstrap returns Config to the Thing with provided external ID using external key.
	Bootstrap(externalKey, externalID string) (BootstrapConfig, error)

	// Whitelist updates Thing state Config with given ID belonging to the user identified by the given token.
	Whitelist(token string, cfg BootstrapConfig) error

	// IssueCert issues a certificate for a thing required for mtls.
	IssueCert(thingID string, keyBits int, keyType, valid, token string) (Cert, error)

	// RemoveCert removes a certificate
	RemoveCert(id, token string) error

	// RevokeCert revokes certificate with certID for thing with thingID
	RevokeCert(thingID, certID, token string) error
}

SDK contains Mainflux API.

func NewSDK

func NewSDK(conf Config) SDK

NewSDK returns new mainflux SDK instance.

type Thing

type Thing struct {
	ID       string                 `json:"id,omitempty"`
	Name     string                 `json:"name,omitempty"`
	Key      string                 `json:"key,omitempty"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

Thing represents mainflux thing.

type ThingsPage

type ThingsPage struct {
	Things []Thing `json:"things"`
	// contains filtered or unexported fields
}

ThingsPage contains list of things in a page with proper metadata.

type User

type User struct {
	ID       string                 `json:"id,omitempty"`
	Email    string                 `json:"email,omitempty"`
	Groups   []string               `json:"groups,omitempty"`
	Password string                 `json:"password,omitempty"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

User represents mainflux user its credentials.

type UserPasswordReq

type UserPasswordReq struct {
	OldPassword string `json:"old_password,omitempty"`
	Password    string `json:"password,omitempty"`
}

UserPasswordReq contains old and new passwords

type UsersPage

type UsersPage struct {
	Users []User `json:"users"`
	// contains filtered or unexported fields
}