naos

README

naos

The Networked Artifacts Operating System.

This repository contains the naos go library and command line utility.

CLI

The following commands are offered by the naos command line utility.

Project Management:
  create   Will create a new naos project in the current directory.
  install  Will download required dependencies to the 'naos' subdirectory.
  build    Will build all source files.
  flash    Will flash the previously built binary to an attached device.
  attach   Will open a serial communication with an attached device.
  run      Will run 'build', 'flash' and 'attach' sequentially.
  format   Will format all source files in the 'src' subdirectory.

Fleet Management:
  list     Will list all devices listed in the inventory.
  collect  Will collect devices and add them to the inventory.
  get      Will read a parameter value from devices.
  set      Will set a parameter value on devices.
  unset    Will unset a parameter on devices.
  monitor  Will monitor heartbeats from devices.
  record   Will record log messages from devices.
  debug    Will gather debug information from devices.
  update   Will send the previously built binary to devices.

Usage:
  naos create [--cmake --force]
  naos install [--force]
  naos build [--clean --app-only]
  naos flash [<device>] [--erase --app-only]
  naos attach [<device>] [--simple]
  naos run [<device>] [--clean --app-only --erase --simple]
  naos format
  naos list
  naos collect [--clear --duration=<time>]
  naos get <param> [<pattern>] [--timeout=<time>]
  naos set <param> <value> [<pattern>] [--timeout=<time>]
  naos unset <param> [<pattern>] [--timeout=<time>]
  naos monitor [<pattern>] [--timeout=<time>]
  naos record [<pattern>] [--timeout=<time>]
  naos debug [<pattern>] [--delete --duration=<time>]
  naos update [<pattern>] [--jobs=<count> --timeout=<time>]
  naos help

Options:
  --cmake               Create required CMake files for IDEs like CLion.
  --force               Reinstall dependencies when they already exist.
  --clean               Clean all build artifacts before building again.
  --erase               Erase completely before flashing new image.
  --app-only            Only build or flash the application.
  --simple              Use simple serial tool.
  --clear               Remove not available devices from inventory.
  --delete              Delete loaded coredumps from the devices.
  -d --duration=<time>  Operation duration [default: 2s].
  -t --timeout=<time>   Operation timeout [default: 5s].
  -j --jobs=<count>     Number of simultaneous update jobs [default: 10].

Documentation

Index

• type Component
• type Device
• type Inventory
  • func NewInventory() *Inventory
  • func ReadInventory(path string) (*Inventory, error)
  • func (i *Inventory) Collect(duration time.Duration) ([]*Device, error)
  • func (i *Inventory) Debug(pattern string, delete bool, duration time.Duration) (map[*Device][]byte, error)
  • func (i *Inventory) DeviceBaseTopics(pattern string) []string
  • func (i *Inventory) DeviceByBaseTopic(baseTopic string) *Device
  • func (i *Inventory) FilterDevices(pattern string) []*Device
  • func (i *Inventory) GetParams(pattern, param string, timeout time.Duration) ([]*Device, error)
  • func (i *Inventory) Monitor(pattern string, quit chan struct{}, timeout time.Duration, ...) error
  • func (i *Inventory) Record(pattern string, quit chan struct{}, timeout time.Duration, ...) error
  • func (i *Inventory) Save(path string) error
  • func (i *Inventory) SetParams(pattern, param, value string, timeout time.Duration) ([]*Device, error)
  • func (i *Inventory) UnsetParams(pattern, param string, timeout time.Duration) ([]*Device, error)
  • func (i *Inventory) Update(pattern string, firmware []byte, jobs int, timeout time.Duration, ...) error
• type Project
  • func CreateProject(path string, force, cmake bool, out io.Writer) (*Project, error)
  • func OpenProject(path string) (*Project, error)
  • func (p *Project) Attach(device string, simple bool, out io.Writer, in io.Reader) error
  • func (p *Project) Build(clean, appOnly bool, out io.Writer) error
  • func (p *Project) Debug(pattern string, delete bool, duration time.Duration, out io.Writer) error
  • func (p *Project) Flash(device string, erase bool, appOnly bool, out io.Writer) error
  • func (p *Project) Format(out io.Writer) error
  • func (p *Project) Install(force bool, out io.Writer) error
  • func (p *Project) SaveInventory() error
  • func (p *Project) Tree() string
  • func (p *Project) Update(pattern string, jobs int, timeout time.Duration, ...) error

Types

type Component

type Component struct {
	Repository string `json:"repository"`
	Version    string `json:"version"`
}

A Component represents an installable naos component.

type Device

type Device struct {
	BaseTopic       string            `json:"base_topic"`
	Name            string            `json:"name"`
	Type            string            `json:"type"`
	FirmwareVersion string            `json:"firmware_version"`
	Parameters      map[string]string `json:"parameters"`
}

A Device represents a single device in an Inventory.

type Inventory

type Inventory struct {
	Version    string                `json:"version"`
	Components map[string]*Component `json:"components"`
	Broker     string                `json:"broker"`
	Devices    map[string]*Device    `json:"devices"`
}

A Inventory represents the contents of the inventory file.

func NewInventory

func NewInventory() *Inventory

NewInventory creates a new Inventory.

func ReadInventory

func ReadInventory(path string) (*Inventory, error)

ReadInventory will attempt to read the inventory file at the specified path.

func (*Inventory) Collect

func (i *Inventory) Collect(duration time.Duration) ([]*Device, error)

Collect will collect announcements and update the inventory with found devices for the given amount of time. It will return a list of devices that have been added to the inventory.

func (*Inventory) Debug

func (i *Inventory) Debug(pattern string, delete bool, duration time.Duration) (map[*Device][]byte, error)

Debug will load the coredump data from the devices that match the supplied glob pattern.

func (*Inventory) DeviceBaseTopics

func (i *Inventory) DeviceBaseTopics(pattern string) []string

DeviceBaseTopics returns a list of base topics from devices that match the supplied pattern.

func (*Inventory) DeviceByBaseTopic

func (i *Inventory) DeviceByBaseTopic(baseTopic string) *Device

DeviceByBaseTopic returns the first device that has the matching base topic.

func (*Inventory) FilterDevices

func (i *Inventory) FilterDevices(pattern string) []*Device

FilterDevices will return a list of devices that have a name matching the supplied glob pattern.

func (*Inventory) GetParams

func (i *Inventory) GetParams(pattern, param string, timeout time.Duration) ([]*Device, error)

GetParams will request specified parameter from all devices matching the supplied glob pattern. The inventory is updated with the reported value and a list of answering devices is returned.

func (*Inventory) Monitor

func (i *Inventory) Monitor(pattern string, quit chan struct{}, timeout time.Duration, callback func(*Device, *mqtt.Heartbeat)) error

Monitor will monitor the devices that match the supplied glob pattern and update the inventory accordingly. The specified callback is called for every heartbeat with the update device and the heartbeat available at device.LastHeartbeat.

func (*Inventory) Record

func (i *Inventory) Record(pattern string, quit chan struct{}, timeout time.Duration, callback func(*Device, string)) error

Record will enable log recording mode and yield the received log messages until the provided channel has been closed.

func (*Inventory) Save

func (i *Inventory) Save(path string) error

Save will write the inventory file to the specified path.

func (*Inventory) SetParams

func (i *Inventory) SetParams(pattern, param, value string, timeout time.Duration) ([]*Device, error)

SetParams will set the specified parameter on all devices matching the supplied glob pattern. The inventory is updated with the saved value and a list of updated devices is returned.

func (*Inventory) UnsetParams

func (i *Inventory) UnsetParams(pattern, param string, timeout time.Duration) ([]*Device, error)

UnsetParams will unset the specified parameter on all devices matching the supplied glob pattern. The inventory is updated with the removed value and a list of updated devices is returned.

func (*Inventory) Update

func (i *Inventory) Update(pattern string, firmware []byte, jobs int, timeout time.Duration, callback func(*Device, *mqtt.UpdateStatus)) error

Update will update the devices that match the supplied glob pattern with the specified image. The specified callback is called for every change in state or progress.

type Project

type Project struct {
	Location  string
	Inventory *Inventory
}

A Project is a project available on disk.

func CreateProject

func CreateProject(path string, force, cmake bool, out io.Writer) (*Project, error)

CreateProject will initialize a project in the specified directory. If out is not nil, it will be used to log information about the process.

func OpenProject

func OpenProject(path string) (*Project, error)

OpenProject will open the project in the specified path.

func (*Project) Attach

func (p *Project) Attach(device string, simple bool, out io.Writer, in io.Reader) error

Attach will attach to the attached device.

func (*Project) Build

func (p *Project) Build(clean, appOnly bool, out io.Writer) error

Build will build the project.

func (*Project) Debug

func (p *Project) Debug(pattern string, delete bool, duration time.Duration, out io.Writer) error

Debug will request coredumps from the devices that match the supplied glob pattern. The coredumps are saved to the 'debug' directory in the project.

func (*Project) Flash

func (p *Project) Flash(device string, erase bool, appOnly bool, out io.Writer) error

Flash will flash the project to the attached device.

func (*Project) Format

func (p *Project) Format(out io.Writer) error

Format will format all source files in the project if 'clang-format' is available.

func (*Project) Install

func (p *Project) Install(force bool, out io.Writer) error

Install will download necessary dependencies. Any existing dependencies will be removed if force is set to true. If out is not nil, it will be used to log information about the process.

func (*Project) SaveInventory

func (p *Project) SaveInventory() error

SaveInventory will save the associated inventory to disk.

func (*Project) Tree

func (p *Project) Tree() string

Tree returns the internal directory used to store the toolchain, development framework and other necessary files.

func (*Project) Update

func (p *Project) Update(pattern string, jobs int, timeout time.Duration, callback func(*Device, *mqtt.UpdateStatus)) error

Update will update the devices that match the supplied glob pattern with the previously built image. The specified callback is called for every change in state or progress.