Documentation
¶
Overview ¶
Package knxnet provides the means to parse and generate frames of the KNXnet/IP protocol.
Index ¶
- Constants
- Variables
- func AllocAndPack(srv ServicePackable) []byte
- func Pack(buffer []byte, srv ServicePackable)
- func Size(service ServicePackable) uint
- func Unpack(data []byte, srv *Service) (uint, error)
- func UnpackHeader(data []byte, serviceID *ServiceID, totalLen *uint16) (uint, error)
- type Address
- type ConnReq
- type ConnRes
- type ConnStateReq
- type ConnStateRes
- type DescriptionBlock
- type DescriptionReq
- type DescriptionRes
- type DescriptionType
- type DeviceInformationBlock
- type DeviceSerialNumber
- type DeviceState
- type DeviceStatus
- type DiscReq
- type DiscRes
- type ErrCode
- type HostInfo
- type KNXMedium
- type Port
- type ProjectInstallationIdentifier
- type Protocol
- type RouterSocket
- type RoutingBusy
- type RoutingInd
- type RoutingLost
- type SearchReq
- type SearchRes
- type Service
- type ServiceFamily
- type ServiceFamilyType
- type ServiceID
- type ServicePackable
- type Socket
- type SupportedServicesDIB
- type TunnelLayer
- type TunnelReq
- type TunnelRes
- type TunnelSocket
- type UnknownDescriptionBlock
- type UnknownService
Constants ¶
const ( // ServiceFamilyTypeIPCore is the KNXnet/IP Core family type. ServiceFamilyTypeIPCore = 0x02 // ServiceFamilyTypeIPDeviceManagement is the KNXnet/IP Device Management family type. ServiceFamilyTypeIPDeviceManagement = 0x03 // ServiceFamilyTypeIPTunnelling is the KNXnet/IP Tunnelling family type. ServiceFamilyTypeIPTunnelling = 0x04 // ServiceFamilyTypeIPRouting is the KNXnet/IP Routing family type. ServiceFamilyTypeIPRouting = 0x05 // ServiceFamilyTypeIPRemoteLogging is the KNXnet/IP Remote Logging family type. ServiceFamilyTypeIPRemoteLogging = 0x06 // ServiceFamilyTypeIPRemoteConfigurationAndDiagnosis is the KNXnet/IP Remote Configuration and Diagnosis family type. ServiceFamilyTypeIPRemoteConfigurationAndDiagnosis = 0x07 // ServiceFamilyTypeIPObjectServer is the KNXnet/IP Object Server family type. ServiceFamilyTypeIPObjectServer = 0x08 )
const ( // NoError indicates a successful operation. NoError = 0x00 // ErrHostProtocolType indicates an unsupported host protocol. ErrHostProtocolType = 0x01 // ErrVersionNotSupported indicates an unsupported KNXnet/IP protocol version. ErrVersionNotSupported = 0x02 // ErrSequenceNumber indicates that an out-of-order sequence number has been received. ErrSequenceNumber = 0x04 // ErrConnectionID indicates that there is no active data connection with given ID. ErrConnectionID = 0x21 // ErrConnectionType indicates an unsupported connection type. ErrConnectionType = 0x22 // ErrConnectionOption indicates an unsupported connection option. ErrConnectionOption = 0x23 // ErrNoMoreConnections is returned by a Tunnelling Server when it cannot accept more // connections. ErrNoMoreConnections = 0x24 // ErrNoMoreUniqueConnections is returned by a Tunnelling Server when it has no free Individual // Address available that could be used by the connection. ErrNoMoreUniqueConnections = 0x25 // ErrDataConnection indicates an error with a data connection. ErrDataConnection = 0x26 // ErrKNXConnection indicates an error with a KNX connection. ErrKNXConnection = 0x27 // ErrTunnellingLayer indicates an unsupported tunnelling layer. ErrTunnellingLayer = 0x29 )
What follows are errors codes defined in the KNX standard.
Variables ¶
var ( ErrHeaderLength = errors.New("header length is not 6") ErrHeaderVersion = errors.New("protocol version is not 16") )
These are errors that might occur during unpacking of the header.
Functions ¶
func AllocAndPack ¶
func AllocAndPack(srv ServicePackable) []byte
AllocAndPack allocates a buffer and packs the KNXnet/IP packet into it.
func Pack ¶
func Pack(buffer []byte, srv ServicePackable)
Pack generates a KNXnet/IP packet. Utilize Size() to determine the required size of the buffer.
func Unpack ¶
Unpack parses a KNXnet/IP packet and retrieves its service payload.
On success, the variable pointed to by srv will contain a pointer to a service type. You can cast it to the matching against service type, like so:
var srv Service _, err := Unpack(r, &srv) if err != nil { log.Fatal(err) } switch srv := srv.(type) { case *ConnRes: // ... case *TunnelReq: // ... // ... }
Types ¶
type ConnReq ¶
type ConnReq struct { Control HostInfo Tunnel HostInfo Layer TunnelLayer }
A ConnReq requests a connection to a gateway.
type ConnRes ¶
ConnRes is a response to a connection request.
type ConnStateReq ¶
A ConnStateReq requests the connection state from a gateway.
func (*ConnStateReq) Pack ¶
func (req *ConnStateReq) Pack(buffer []byte)
Pack assembles the service payload in the given buffer.
func (ConnStateReq) Service ¶
func (ConnStateReq) Service() ServiceID
Service returns the service identifier for connection state requests.
type ConnStateRes ¶
A ConnStateRes is a response to a connection state request.
func (*ConnStateRes) Pack ¶
func (res *ConnStateRes) Pack(buffer []byte)
Pack assembles the service payload in the given buffer.
func (ConnStateRes) Service ¶
func (ConnStateRes) Service() ServiceID
Service returns the service identifier for connection state responses.
type DescriptionBlock ¶
type DescriptionBlock struct { DeviceHardware DeviceInformationBlock SupportedServices SupportedServicesDIB UnknownBlocks []UnknownDescriptionBlock }
DescriptionBlock is returned by a Search Request or a Description Request.
type DescriptionReq ¶
type DescriptionReq struct {
HostInfo
}
A DescriptionReq requests a description from a particular KNXnet/IP server via unicast.
func NewDescriptionReq ¶
func NewDescriptionReq(addr net.Addr) (*DescriptionReq, error)
NewDescriptionReq creates a new Description Request, addr defines where KNXnet/IP server should send the response to.
func (DescriptionReq) Service ¶
func (DescriptionReq) Service() ServiceID
Service returns the service identifier for a Description Request.
type DescriptionRes ¶
type DescriptionRes DescriptionBlock
A DescriptionRes is a Description Response from a KNXnet/IP server.
func (*DescriptionRes) Pack ¶
func (res *DescriptionRes) Pack(buffer []byte)
Pack assembles the Description Response structure in the given buffer.
func (DescriptionRes) Service ¶
func (DescriptionRes) Service() ServiceID
Service returns the service identifier for Description Response.
func (DescriptionRes) Size ¶
func (res DescriptionRes) Size() uint
Size returns the packed size of a Description Response.
type DescriptionType ¶
type DescriptionType uint8
DescriptionType describes the type of a DeviceInformationBlock.
const ( // DescriptionTypeDeviceInfo describes Device information e.g. KNX medium. DescriptionTypeDeviceInfo DescriptionType = 0x01 // DescriptionTypeSupportedServiceFamilies describes Service families supported by the device. DescriptionTypeSupportedServiceFamilies DescriptionType = 0x02 // DescriptionTypeIPConfig describes IP configuration. DescriptionTypeIPConfig DescriptionType = 0x03 // DescriptionTypeIPCurrentConfig describes current IP configuration. DescriptionTypeIPCurrentConfig DescriptionType = 0x04 // DescriptionTypeKNXAddresses describes KNX addresses. DescriptionTypeKNXAddresses DescriptionType = 0x05 // DescriptionTypeManufacturerData describes a DIB structure for further data defined by device manufacturer. DescriptionTypeManufacturerData DescriptionType = 0xfe )
type DeviceInformationBlock ¶
type DeviceInformationBlock struct { Type DescriptionType Medium KNXMedium Status DeviceStatus Source cemi.IndividualAddr ProjectIdentifier ProjectInstallationIdentifier SerialNumber DeviceSerialNumber RoutingMulticastAddress Address HardwareAddr net.HardwareAddr FriendlyName string }
DeviceInformationBlock contains information about a device.
func (*DeviceInformationBlock) Pack ¶
func (info *DeviceInformationBlock) Pack(buffer []byte)
Pack assembles the device information structure in the given buffer.
func (DeviceInformationBlock) Size ¶
func (DeviceInformationBlock) Size() uint
Size returns the packed size.
type DeviceSerialNumber ¶
type DeviceSerialNumber [6]byte
DeviceSerialNumber desribes the serial number of a device.
type DeviceState ¶
type DeviceState uint8
DeviceState indicates the state of a device.
const ( DeviceStateOk DeviceState = 0x00 DeviceStateKNXError DeviceState = 0x01 DeviceStateIPError DeviceState = 0x02 DeviceStateReserved DeviceState = 0xfc )
These are known device states.
func (DeviceState) String ¶
func (status DeviceState) String() string
String converts the device status to a string.
type DiscReq ¶
A DiscReq requests a connection to be terminated.
type DiscRes ¶
A DiscRes is a response to a disconnect request.
type HostInfo ¶
HostInfo contains information about a host.
func HostInfoFromAddress ¶
HostInfoFromAddress returns HostInfo from an address.
type ProjectInstallationIdentifier ¶
type ProjectInstallationIdentifier uint16
ProjectInstallationIdentifier describes a KNX project installation identifier.
type RouterSocket ¶
type RouterSocket struct {
// contains filtered or unexported fields
}
RouterSocket is a UDP socket for KNXnet/IP packet exchange.
func ListenRouter ¶
func ListenRouter(multicastAddress string) (*RouterSocket, error)
ListenRouter creates a new Socket which can be used to exchange KNXnet/IP packets with multiple endpoints.
func ListenRouterOnInterface ¶
func ListenRouterOnInterface(ifi *net.Interface, multicastAddress string, multicastLoopbackEnabled bool) (*RouterSocket, error)
ListenRouterOnInterface creates a new Socket which can be used to exchange KNXnet/IP packets with multiple endpoints. The interface is used to send or listen for KNXnet/IP packets. If the interface is nil, the system-assigned multicast interface is used.
func (*RouterSocket) Addr ¶
func (sock *RouterSocket) Addr() *net.UDPAddr
Addr returns the multicast destination address.
func (*RouterSocket) Close ¶
func (sock *RouterSocket) Close() error
Close shuts the socket down. This will indirectly terminate the associated workers.
func (*RouterSocket) Inbound ¶
func (sock *RouterSocket) Inbound() <-chan Service
Inbound provides a channel from which you can retrieve incoming packets.
func (*RouterSocket) LocalAddr ¶
func (sock *RouterSocket) LocalAddr() net.Addr
LocalAddr returns the local UDP address.
func (*RouterSocket) Send ¶
func (sock *RouterSocket) Send(payload ServicePackable) error
Send transmits a KNXnet/IP packet.
type RoutingBusy ¶
type RoutingBusy struct { // Device status Status DeviceState // Time to wait WaitTime time.Duration // If set to 0x00, must pause sending Control uint16 }
A RoutingBusy indicates that a router is busy.
func (RoutingBusy) Service ¶
func (RoutingBusy) Service() ServiceID
Service returns the service identifiers for routing busy indication.
type RoutingInd ¶
A RoutingInd indicates to one or more routers that the contents shall be routed.
func (*RoutingInd) Pack ¶
func (ind *RoutingInd) Pack(buffer []byte)
Pack assembles the service payload in the given buffer.
func (RoutingInd) Service ¶
func (RoutingInd) Service() ServiceID
Service returns the service identifiers for routing indication.
type RoutingLost ¶
type RoutingLost struct { // Device status Status DeviceState // Number of packets lost Count uint16 }
A RoutingLost indicates that a packet got lost.
func (RoutingLost) Service ¶
func (RoutingLost) Service() ServiceID
Service returns the service identifiers for routing lost indication.
type SearchReq ¶
type SearchReq struct {
HostInfo
}
A SearchReq requests a discovery from all KNXnet/IP servers via multicast.
func NewSearchReq ¶
NewSearchReq creates a new SearchReq, addr defines where KNXnet/IP server should send the reponse to.
type SearchRes ¶
type SearchRes struct { Control HostInfo DescriptionB DescriptionBlock }
A SearchRes is a Search Response from a KNXnet/IP server.
type Service ¶
type Service interface {
Service() ServiceID
}
Service describes a KNXnet/IP service.
type ServiceFamily ¶
type ServiceFamily struct { Type ServiceFamilyType Version uint8 }
ServiceFamily describes a KNXnet service supported by a device.
func (*ServiceFamily) Pack ¶
func (f *ServiceFamily) Pack(buffer []byte)
Pack assembles the service family structure in the given buffer.
type ServiceFamilyType ¶
type ServiceFamilyType uint8
ServiceFamilyType describes a KNXnet service family type.
type ServiceID ¶
type ServiceID uint16
ServiceID identifies the service that is contained in a packet.
const ( SearchReqService ServiceID = 0x0201 SearchResService ServiceID = 0x0202 DescrReqService ServiceID = 0x0203 DescrResService ServiceID = 0x0204 ConnReqService ServiceID = 0x0205 ConnResService ServiceID = 0x0206 ConnStateReqService ServiceID = 0x0207 ConnStateResService ServiceID = 0x0208 DiscReqService ServiceID = 0x0209 DiscResService ServiceID = 0x020a TunnelReqService ServiceID = 0x0420 TunnelResService ServiceID = 0x0421 RoutingIndService ServiceID = 0x0530 RoutingLostService ServiceID = 0x0531 RoutingBusyService ServiceID = 0x0532 )
Currently supported services.
type ServicePackable ¶
ServicePackable combines Packable and Service.
type Socket ¶
type Socket interface { Send(payload ServicePackable) error Inbound() <-chan Service Close() error LocalAddr() net.Addr }
A Socket is a socket, duh.
type SupportedServicesDIB ¶
type SupportedServicesDIB struct { Type DescriptionType Families []ServiceFamily }
SupportedServicesDIB contains information about the supported services of a device.
func (*SupportedServicesDIB) Pack ¶
func (sdib *SupportedServicesDIB) Pack(buffer []byte)
Pack assembles the supported services structure in the given buffer.
func (SupportedServicesDIB) Size ¶
func (sdib SupportedServicesDIB) Size() uint
Size returns the packed size.
type TunnelLayer ¶
type TunnelLayer uint8
TunnelLayer identifies the tunnelling layer for a tunnelling connection.
const ( // TunnelLayerData establishes a data-link layer tunnel. Send and receive L_Data.* messages. TunnelLayerData TunnelLayer = 0x02 // TunnelLayerRaw establishes a raw tunnel. Send and receive L_Raw.* messages. TunnelLayerRaw TunnelLayer = 0x04 // TunnelLayerBusmon establishes a bus monitor tunnel. Receive L_Busmon.ind messages. TunnelLayerBusmon TunnelLayer = 0x80 )
type TunnelReq ¶
type TunnelReq struct { // Communication channel Channel uint8 // Sequential number, used to track acknowledgements SeqNumber uint8 // Data to be tunneled Payload cemi.Message }
A TunnelReq asks a gateway to transmit data.
type TunnelRes ¶
type TunnelRes struct { // Communication channel Channel uint8 // Identifies the request that is being acknowledged SeqNumber uint8 // Status code, determines whether the tunneling succeeded or not Status ErrCode }
A TunnelRes is a response to a TunnelRequest. It acts as an acknowledgement.
type TunnelSocket ¶
type TunnelSocket struct {
// contains filtered or unexported fields
}
TunnelSocket is a UDP socket for KNXnet/IP packet exchange.
func DialTunnelTCP ¶
func DialTunnelTCP(address string) (*TunnelSocket, error)
DialTunnelTCP creates a new Socket which can used to exchange KNXnet/IP packets with a single endpoint through TCP.
func DialTunnelUDP ¶
func DialTunnelUDP(address string) (*TunnelSocket, error)
DialTunnelUDP creates a new Socket which can used to exchange KNXnet/IP packets with a single endpoint through UDP.
func (*TunnelSocket) Close ¶
func (sock *TunnelSocket) Close() error
Close shuts the socket down. This will indirectly terminate the associated workers.
func (*TunnelSocket) Inbound ¶
func (sock *TunnelSocket) Inbound() <-chan Service
Inbound provides a channel from which you can retrieve incoming packets.
func (*TunnelSocket) LocalAddr ¶
func (sock *TunnelSocket) LocalAddr() net.Addr
LocalAddr returns the local UDP address.
func (*TunnelSocket) Send ¶
func (sock *TunnelSocket) Send(payload ServicePackable) error
Send transmits a KNXnet/IP packet.
type UnknownDescriptionBlock ¶
type UnknownDescriptionBlock struct { Type DescriptionType Data []byte }
UnknownDescriptionBlock is a placeholder for unknown DIBs.
type UnknownService ¶
type UnknownService struct { Data []byte // contains filtered or unexported fields }
UnknownService is the payload of an unknown service.
func (*UnknownService) Pack ¶
func (us *UnknownService) Pack(buffer []byte)
Pack the payload into the buffer.
func (*UnknownService) Service ¶
func (us *UnknownService) Service() ServiceID
Service returns the service identifier.
func (*UnknownService) Size ¶
func (us *UnknownService) Size() uint
Size returns the size of the payload.