insteon

package module
v0.0.0-...-fe5e139 Latest Latest
Warning

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

 Go to latest Published: Jan 6, 2022 License: Apache-2.0 Imports: 11 Imported by: 0

README

Go Insteon

Go Report Card Build Status GoDoc Coverage Status

This package provides a Go interface to Insteon networks and the ability to control Insteon devices. This package is being actively developed and the API is subject to change. Consider this library to be in an alpha stage of development

CLI Utility

The package provides the "ic" command line tool to perform various administrative tasks related to the Insteon network and its devices.

Insteon Network Daemon

TODO: A REST interface to the Insteon network. Will include abstractions for common tasks such as creating virtual N-Way light switches as well as scenes

Insteon Network Client

TODO: A client application to the Insteon Network Daemon

API

The package can be used directly from other go programs by means of the github.com/abates/insteon package. See the godocs for more information.

Documentation/Notes

Documentation

Index

Constants

View Source 
const (
	GeneralizeDomain        Domain = 0x00
	DimmerDomain                   = 0x01
	SwitchDomain                   = 0x02
	NetworkDomain                  = 0x03
	IrrigationDomain               = 0x04
	ThermostatDomain               = 0x05
	PoolSpaDomain                  = 0x06
	SensorActuatorDomain           = 0x07
	HomeEntertainmentDomain        = 0x08
	EnergyMgmtDomain               = 0x09
	ApplianceDomain                = 0x0a
	PlumbingDomain                 = 0x0b
	CommunicationDomain            = 0x0c
	ComputerDomain                 = 0x0d
	WindowCoveringsDomain          = 0x0e
	AccessDomain                   = 0x0f
	SecurityDomain                 = 0x10
	SurveillanceDomain             = 0x11
	AutomotiveDomain               = 0x12
	PetCareDomain                  = 0x13
	ToysDomain                     = 0x14
	TimekeepingDomain              = 0x15
	HolidayDomain                  = 0x16
	UnassignedDomain               = 0xff
)
View Source 
const (
	AvailableController   = RecordControlFlags(0x40)
	UnavailableController = RecordControlFlags(0xc0)
	AvailableResponder    = RecordControlFlags(0x00)
	UnavailableResponder  = RecordControlFlags(0x80)
)

RecordControlFlags indicating the different availability/type of link records

View Source 
const (
	// StandardMsgLen is the length of an insteon standard message minus one byte (the crc byte)
	StandardMsgLen = 9

	// ExtendedMsgLen is the length of an insteon extended message minus one byte (the crc byte)
	ExtendedMsgLen = 23
)
View Source 
const (
	MsgTypeDirect            MessageType = 0    // D       0b0000 0000
	MsgTypeDirectAck                     = 0x20 // D (Ack) 0b0010 0000
	MsgTypeDirectNak                     = 0xA0 // D (Nak) 0b1010 0000
	MsgTypeAllLinkCleanup                = 0x40 // C       0b0100 0000
	MsgTypeAllLinkCleanupAck             = 0x60 // C (Ack) 0b0110 0000
	MsgTypeAllLinkCleanupNak             = 0xE0 // C (Nak) 0b1110 0000
	MsgTypeBroadcast                     = 0x80 // B       0b1000 0000
	MsgTypeAllLinkBroadcast              = 0xC0 // A       0b1100 0000
)

All of the valid message types

View Source 
const (
	StandardBroadcast        = Flags(0x8a)
	StandardAllLinkBroadcast = Flags(0xca)
	StandardDirectMessage    = Flags(0x0a)
	StandardDirectAck        = Flags(0x2a)
	StandardDirectNak        = Flags(0xaa)
	ExtendedDirectMessage    = Flags(0x1a)
	ExtendedDirectAck        = Flags(0x3a)
	ExtendedDirectNak        = Flags(0xba)
)

Flags for common message types

Variables

View Source 
var (
	// ErrBufferTooShort indicates a buffer underrun when unmarshalling data
	ErrBufferTooShort = errors.New("Buffer is too short")

	// ErrReadTimeout indicates the timeout period expired while waiting for
	// a specific message
	ErrReadTimeout = errors.New("Read Timeout")

	// ErrAckTimeout indicates the timeout period expired while waiting for
	// ack message for a previously sent Direct message
	ErrAckTimeout = errors.New("Ack Timeout")

	// ErrWriteTimeout indicates the timeout period expired while waiting to
	// write a message
	ErrWriteTimeout = errors.New("Write Timeout")

	// ErrNotSupported indicates some feature (namely an updateable All-Link database) is
	// not supported by the underlying Insteon device
	ErrNotSupported = errors.New("Feature is not supported by the device")

	// ErrNotImplemented indicates that a device function has not yet been implemented
	ErrNotImplemented = errors.New("Command is not yet implemented")

	// ErrNotLinkable indicates a linking function was requested on a non-linkable device
	ErrNotLinkable = errors.New("Device is not remotely linkable")

	// ErrUnknownCommand is returned by the device (as a Nak) in response to an unknown command byte
	ErrUnknownCommand = errors.New("Unknown command")

	// ErrUnknown is returned by a connection when a NAK occurred but the error code
	// is not known
	ErrUnknown = errors.New("Device returned unknown error")

	// ErrPreNak is returned by I2Cs devices (this error condition is not documented)
	ErrPreNak = errors.New("Database search took too long")

	// ErrAddrFormat is returned when unmarshalling an address from text and the
	// text is in an unsupported format
	ErrAddrFormat = errors.New("address format is xx.xx.xx (digits in hex)")

	// ErrInvalidMemAddress indicates a link record memory address is invalid
	ErrInvalidMemAddress = errors.New("Invalid memory address")

	// ErrVersion is returned when an engine version value is not known
	ErrVersion = errors.New("Unknown Insteon Engine Version")
)

Functions

func PropagationDelay 

func PropagationDelay(ttl uint8, l int) (pd time.Duration)

PropagationDelay attempts to calculate the amount of time an Insteon message needs in order to completely propagate (including relays) throughout the network. This is based on the number of AC zero crossings, the number of times a message can be repeated (ttl) and whether or not the message is an extended message

Types

type Address 

type Address uint32

Address is a 3 byte insteon address

func (*Address) Bytes 

func (a *Address) Bytes() []byte

func (*Address) Get 

func (a *Address) Get() interface{}

Set satisfies the flag.Getter interface

func (Address) MarshalJSON 

func (a Address) MarshalJSON() ([]byte, error)

MarshalJSON will convert the address to a JSON string

func (Address) MarshalText 

func (a Address) MarshalText() ([]byte, error)

MarshalText fulfills the requiresments of encoding.TextMarshaler so that Address can be used as a map key in other encoding

func (*Address) Put 

func (a *Address) Put(buf []byte)

func (*Address) Set 

func (a *Address) Set(str string) error

Set satisfies the flag.Value interface

func (Address) String 

func (a Address) String() string

String will format the Address object into a form common to Insteon devices: 00.00.00 where each byte is represented in hexadecimal form (e.g. 01.b4.a5) the string will always be 8 characters long, bytes are zero padded

func (*Address) UnmarshalJSON 

func (a *Address) UnmarshalJSON(data []byte) (err error)

UnmarshalJSON will populate the address from the input JSON string

func (*Address) UnmarshalText 

func (a *Address) UnmarshalText(text []byte) error

UnmarshalText converts a human readable string into an Insteon address. If the address cannot be parsed then UnmarshalText returns an ErrAddressFormat error

type Category 

type Category byte

Category indicates the specific kind of device within a domain. For instance, a LampLing and a SwitchLinc Dimmer are both within the Dimmable device domain

type DevCat 

type DevCat [2]byte

DevCat is a 2 byte value including a device category and sub-category. Devices are grouped by categories (thermostat, light, etc) and then each category has specific types of devices such as on/off switches and dimmer switches

func (DevCat) Category 

func (dc DevCat) Category() Category

Category returns the device's category. For instance a DevCat with the Domain "Dimmable" may return the Category for LampLinc or SwitchLinc Dimmer

func (DevCat) Domain 

func (dc DevCat) Domain() Domain

Domain returns what device domain a particular device belongs to

func (DevCat) In 

func (dc DevCat) In(domains ...Domain) bool

In determines if the DevCat domain is found in the list

func (DevCat) MarshalJSON 

func (dc DevCat) MarshalJSON() ([]byte, error)

MarshalJSON will convert the DevCat to a valid JSON byte string

func (DevCat) String 

func (dc DevCat) String() string

String returns a string representation of the DevCat in the form of category.subcategory where those fields are the 2 digit hex representation of their corresponding values

func (*DevCat) UnmarshalJSON 

func (dc *DevCat) UnmarshalJSON(data []byte) (err error)

UnmarshalJSON will unmarshal the input json byte string into the DevCat receiver

type Domain 

type Domain byte

Domain represents an entire domain of similar devices (dimmers, switches, thermostats, etc)

type EngineVersion 

type EngineVersion int

EngineVersion indicates the Insteon engine version that the device is running 

const (
	VerI1 EngineVersion = iota
	VerI2
	VerI2Cs
)

Insteon Engine Versions

func (EngineVersion) String 

func (ev EngineVersion) String() string

type FirmwareVersion 

type FirmwareVersion int

FirmwareVersion indicates the software/firmware revision number of a device

func (FirmwareVersion) String 

func (fv FirmwareVersion) String() string

String will return the hexadecimal string of the firmware version

type Flags 

type Flags byte

Flags is the flags byte in an insteon message

func Flag 

func Flag(messageType MessageType, extended bool, hopsLeft, maxHops uint8) Flags

Flag allows building of MessageFlags from component parts.

func (Flags) Ack 

func (f Flags) Ack() bool

Ack indicates if the message was an acknowledgement

func (Flags) Extended 

func (f Flags) Extended() bool

Extended will indicate if the insteon message is extended length

func (Flags) MaxTTL 

func (f Flags) MaxTTL() uint8

MaxTTL is the maximum number of times a message can be repeated

func (Flags) Nak 

func (f Flags) Nak() bool

Nak indicates if the message was a negative-acknowledgement

func (*Flags) SetMaxTTL 

func (f *Flags) SetMaxTTL(ttl uint8)

func (*Flags) SetTTL 

func (f *Flags) SetTTL(ttl uint8)

func (Flags) Standard 

func (f Flags) Standard() bool

Standard will indicate if the insteon message is standard length

func (Flags) String 

func (f Flags) String() string

func (Flags) TTL 

func (f Flags) TTL() uint8

TTL is the remaining number of times an insteon message will be retransmitted. This is decremented each time a message is repeated

func (Flags) Type 

func (f Flags) Type() MessageType

Type will return the MessageType of the flags

type Group 

type Group byte

Group is the Insteon group to which the Link Record corresponds

func (*Group) Get 

func (g *Group) Get() interface{}

func (*Group) Set 

func (g *Group) Set(s string) error

func (*Group) String 

func (g *Group) String() string

String representation of the group number

func (*Group) UnmarshalText 

func (g *Group) UnmarshalText(text []byte) error

UnmarshalText takes an input string and converts it to its Group equivalent. The decimal input value must be positive and less than 256

type LinkID 

type LinkID [5]byte

LinkID is the combination of bit 6 of the record control flags (controller/responder), the group ID and the 3 byte address

type LinkRecord 

type LinkRecord struct {
	Flags   RecordControlFlags `json:"flags"`
	Group   Group              `json:"group"`
	Address Address            `json:"address"`
	Data    [3]byte            `json:"data"`
}

LinkRecord is a single All-Link record in an All-Link database 

func ControllerLink(group Group, address Address) LinkRecord

ControllerLink creates a LinkRecord that is set as a controller record with the group and responder address set to the given arguments 

func ResponderLink(group Group, address Address) LinkRecord

ResponderLink creates a LinkRecord that is set as a responder record with the group and controller address set to the given arguments

func (*LinkRecord) Equal 

func (l *LinkRecord) Equal(other *LinkRecord) bool

Equal will determine if another LinkRecord is equivalent. The records are equivalent if they both have the same availability, type (controller/responder) address and group

func (*LinkRecord) ID 

func (l *LinkRecord) ID() LinkID

func (*LinkRecord) MarshalBinary 

func (l *LinkRecord) MarshalBinary() ([]byte, error)

MarshalBinary converts the link-record to a byte string that can be used in a record request

func (*LinkRecord) MarshalText 

func (l *LinkRecord) MarshalText() ([]byte, error)

MarshalText will convert the LinkRecord to a text string that can be used as input to the UnmarshalText. This is useful in allowing a user to manuall edit link records

func (LinkRecord) String 

func (l LinkRecord) String() string

String converts the LinkRecord to a human readable string that looks similar to: 

UR        1 01.02.03   00 1c 01

func (*LinkRecord) UnmarshalBinary 

func (l *LinkRecord) UnmarshalBinary(buf []byte) (err error)

UnmarshalBinary will convert the byte string received in a message request to a LinkRecord

func (*LinkRecord) UnmarshalText 

func (l *LinkRecord) UnmarshalText(buf []byte) (err error)

UnmarshalText takes an input text string and assigns the values to the RecordControlFlags receiver. The input text string should be in the following form: 

Flags Group Address    Data
UR        1 01.02.03   00 1c 01

Each field is unmarshaled using the corresponding type's UnmarshalText functions

type Message 

type Message struct {
	Src Address
	Dst Address
	Flags
	Command commands.Command
	Payload []byte
}

Message is a single insteon message

func ReadWithTimeout 

func ReadWithTimeout(ch <-chan *Message, timeout time.Duration) (msg *Message, err error)

ReadWithTimeout will attempt to read a message from a channel and will return the read message. If no message is received after the timeout duration, then ErrReadTimeout is returned

func (*Message) Duplicate 

func (m *Message) Duplicate(other *Message) bool

Duplicate indicates whether everything except the ttl matches the other message. This is usefule for detecting re-transmitted messages where the ttl is decremented

func (*Message) Equals 

func (m *Message) Equals(other *Message) bool

func (*Message) MarshalBinary 

func (m *Message) MarshalBinary() (data []byte, err error)

MarshalBinary will convert the Message to a byte slice appropriate for sending out onto the insteon network

func (*Message) String 

func (m *Message) String() (str string)

func (*Message) UnmarshalBinary 

func (m *Message) UnmarshalBinary(data []byte) (err error)

UnmarshalBinary will take a byte slice and unmarshal it into the Message fields

type MessageType 

type MessageType int

MessageType is an integer representing the type of message (Direct, Direct ACK, etc). The following table displays the bit setting tha correspond to the message flags for the various message types: Flags (8 Bit/1 Byte) 

Description        | Message Type (3 bits)
Direct             | 0 0 0
Direct Ack         | 0 0 1
AllLink Cleanup    | 0 1 0
AllLink CleanupAck | 0 1 1
Broadcast          | 1 0 0
Direct Nak         | 1 0 1
AllLink Broadcast  | 1 1 0
AllLink CleanupNak | 1 1 1

func (m MessageType) AllLink() bool

func (MessageType) Broadcast 

func (m MessageType) Broadcast() bool

Broadcast will indicate whether the MessageType represents a broadcast message

func (MessageType) Direct 

func (m MessageType) Direct() bool

Direct will indicate whether the MessageType represents a direct message

func (MessageType) String 

func (m MessageType) String() string

type ProductKey 

type ProductKey [3]byte

ProductKey is a 3 byte code assigned by Insteon

func (ProductKey) String 

func (p ProductKey) String() string

String returns the hexadecimal string for the product key

type RecordControlFlags 

type RecordControlFlags byte

RecordControlFlags indicate whether a link record is a controller or responder and whether it is available or in use

func (RecordControlFlags) Available 

func (rcf RecordControlFlags) Available() bool

Available indicates if a link record is available and can be overwritten by a new record. Available is synonmous with "deleted"

func (*RecordControlFlags) ClearLastRecord 

func (rcf *RecordControlFlags) ClearLastRecord()

func (RecordControlFlags) Controller 

func (rcf RecordControlFlags) Controller() bool

Controller indicates that the device is a controller for the device in the link record

func (RecordControlFlags) InUse 

func (rcf RecordControlFlags) InUse() bool

InUse indicates if a link record is currently in use by the device

func (RecordControlFlags) LastRecord 

func (rcf RecordControlFlags) LastRecord() bool

LastRecord indicates if this link record is the last record (also known as the high water mark) in the database.

func (RecordControlFlags) Responder 

func (rcf RecordControlFlags) Responder() bool

Responder indicates that the device is a reponder to the device listed in the link record

func (*RecordControlFlags) SetAvailable 

func (rcf *RecordControlFlags) SetAvailable()

SetAvailable indicates that the record is no longer in use and can be overwritten

func (*RecordControlFlags) SetController 

func (rcf *RecordControlFlags) SetController()

func (*RecordControlFlags) SetInUse 

func (rcf *RecordControlFlags) SetInUse()

SetInUse indicates the the record is active/in use and cannot be overwritten

func (*RecordControlFlags) SetLastRecord 

func (rcf *RecordControlFlags) SetLastRecord()

func (*RecordControlFlags) SetResponder 

func (rcf *RecordControlFlags) SetResponder()

func (RecordControlFlags) String 

func (rcf RecordControlFlags) String() string

String will be "A" or "U" (available or in use) followed by "C" or "R" (controller or responder). This string will always be two characters wide

func (*RecordControlFlags) UnmarshalText 

func (rcf *RecordControlFlags) UnmarshalText(text []byte) (err error)

UnmarshalText takes a two character input string and converts it to the correct RecordControlFlags. The first character can be either "A" for available or "U" for unavailable (in use) and the second character is either "C" for controller or "R" for responder

Source Files

View all Source files

Directories

Path Synopsis
cmd
anonymize
ic
isnoop
iwalk

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.