airthings

Documentation

Overview

Package airthings integrates AirThings devices into Smart Core. AirThings manufacture sensors, typically air quality sensors, that connect directly to their cloud. The cloud API provides access to various information about the devices and sites. The primary api used by this driver is the "location latest samples" api. See https://developer.airthings.com/api-docs#tag/Locations/paths/~1v1~1locations~1%7BlocationId%7D~1latest-samples/get

The driver pulls all data into a local model, then translates that local model into Smart Core traits. Package local defines the local model. The code that pulls the data from the AirThings cloud API into local is in [client.go]. The supported traits are defined in [traits.go].

Index

• Constants
• Variables
• type Auth
  • func (a Auth) ClientCredentialsConfig() (clientcredentials.Config, error)
• type ClientSecret
  • func (c ClientSecret) Read() (string, error)
• type Config
  • func (c Config) URL(p string, args ...any) string
• type Device
• type Driver
• type Location

Constants

const (
	DefaultTokenURL = "https://accounts-api.airthings.com/v1/token"
	DefaultBaseURL  = "https://ext-api.airthings.com"
	DefaultPoll     = time.Minute
)

const DriverName = "airthings"

Variables

var (
	DefaultScopes = []string{"read:device"}
)

var Factory driver.Factory = factory{}

Types

type Auth

type Auth struct {
	ClientID string `json:"clientID,omitempty"`
	ClientSecret
	TokenURL string   `json:"tokenURL,omitempty"` // default: "https://accounts-api.airthings.com/v1/token"
	Scopes   []string `json:"scopes,omitempty"`   // default: ["read:device"]
}

func (Auth) ClientCredentialsConfig

func (a Auth) ClientCredentialsConfig() (clientcredentials.Config, error)

type ClientSecret

type ClientSecret struct {
	ClientSecret     string `json:"clientSecret,omitempty"`
	ClientSecretFile string `json:"clientSecretFile,omitempty"`
}

ClientSecret allows specifying a client secret either directly or via a file.

func (ClientSecret) Read

func (c ClientSecret) Read() (string, error)

Read returns the password, either from ClientSecret or ClientSecretFile.

type Config

type Config struct {
	driver.BaseConfig
	Auth    Auth   `json:"auth,omitempty"`
	BaseURL string `json:"baseUrl,omitempty"` // default: "https://ext-api.airthings.com"

	Locations []Location `json:"locations,omitempty"`
}

func (Config) URL

func (c Config) URL(p string, args ...any) string

URL returns the full API URL for the given path. Path should start with a slash.

Example:

c.BaseURL = "https://ext-api.airthings.com"
c.URL("/v1/locations")
// "https://ext-api.airthings.com/v1/locations"
c.URL("/v1/locations/%v/latest-samples", 123)
// "https://ext-api.airthings.com/v1/locations/123/latest-samples"

type Device

type Device struct {
	ID       string           `json:"id,omitempty"`       // AirThings segment ID
	Name     string           `json:"name,omitempty"`     // Smart Core name
	Metadata *traits.Metadata `json:"metadata,omitempty"` // Announced metadata for this SC device
	// Traits lists the trait names to announce for this device.
	// Status is always announced.
	// See traits.go for supported trait names.
	Traits []string `json:"traits,omitempty"`
}

type Driver

type Driver struct {
	*service.Service[Config]
	driver.Services
	// contains filtered or unexported fields
}

type Location

type Location struct {
	// One of ID or Name must be set.
	// If both are set ID takes precedence.
	ID   string `json:"id,omitempty"`
	Name string `json:"name,omitempty"`

	Poll *jsontypes.Duration `json:"poll,omitempty"` // default: 1m

	Devices []Device `json:"devices,omitempty"`
}