knx_core/

knxnetip.rs

use core::convert::TryFrom;

use crate::{IndividualAddress, KnxError, Result};

/// The length of the KNXnet/IP header itself, in octets. The header states
/// this in its own first octet, so a frame that opens with anything else is
/// not a header this crate reads.
pub const HEADER_LENGTH: u8 = 0x06;

/// The protocol version octet for KNXnet/IP 1.0, the only version this crate
/// speaks: the major version in the high nibble, the minor in the low one.
pub const PROTOCOL_VERSION_1_0: u8 = 0x10;

/// The KNXnet/IP services this crate speaks: a chosen subset of the
/// registry, not the complete set.
///
/// Each variant is the 2-octet service-type identifier the header carries,
/// and a code outside this set is refused as
/// [`KnxError::UnsupportedServiceType`] rather than passed along
/// uninterpreted. [`ServiceType::ALL`] fixes the count in its own type, so
/// widening what this crate speaks is an edit to a count the declaration
/// states.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(u16)]
pub enum ServiceType {
    /// A client's search for KNXnet/IP servers, addressed to the
    /// discovery endpoint the caller chose - the system setup
    /// multicast group, a broadcast, or a unicast target alike - and
    /// naming the endpoint it wants answers sent to.
    SearchRequest = 0x0201,
    /// A server's answer to a search: its own control endpoint, and a
    /// description of what it is.
    SearchResponse = 0x0202,
    /// A client's request, addressed to a single server's control endpoint,
    /// for that server's self-description.
    DescriptionRequest = 0x0203,
    /// A server's self-description, answering a description request.
    DescriptionResponse = 0x0204,
    /// A client's request to open a connection, naming its control and data
    /// endpoints and the kind of connection it wants.
    ConnectRequest = 0x0205,
    /// A server's answer to a connect request: the channel it opened and the
    /// connection response data that goes with it, or the reason it refused.
    ConnectResponse = 0x0206,
    /// A client's heartbeat, asking whether the channel it names is still
    /// open. A connection the client stops asking about is one the server
    /// eventually closes on its own.
    ConnectionStateRequest = 0x0207,
    /// A server's answer to a heartbeat, stating the channel's state.
    ConnectionStateResponse = 0x0208,
    /// Either peer's statement that it is closing the channel it names.
    DisconnectRequest = 0x0209,
    /// The answer that completes a disconnect; the channel is closed either
    /// way, so this confirms rather than permits.
    DisconnectResponse = 0x020a,
    /// A cEMI frame carried over a tunnelling connection, stamped with the
    /// channel it belongs to and the sequence number its acknowledgement
    /// answers.
    TunnellingRequest = 0x0420,
    /// The acknowledgement of 1 tunnelling request, naming the sequence
    /// number it answers.
    TunnellingAck = 0x0421,
    /// A cEMI frame multicast to the routing group. Nothing acknowledges it
    /// and it carries no channel or sequence number.
    RoutingIndication = 0x0530,
    /// A router's report that it dropped routing frames it had no room for,
    /// and how many.
    RoutingLostMessage = 0x0531,
    /// A router's request that senders pause, stating how long it expects to
    /// stay saturated.
    RoutingBusy = 0x0532,
}

impl ServiceType {
    /// All `ServiceType` variants in declaration order; the canonical single
    /// source for iteration/decoding.
    pub const ALL: [ServiceType; 15] = [
        ServiceType::SearchRequest,
        ServiceType::SearchResponse,
        ServiceType::DescriptionRequest,
        ServiceType::DescriptionResponse,
        ServiceType::ConnectRequest,
        ServiceType::ConnectResponse,
        ServiceType::ConnectionStateRequest,
        ServiceType::ConnectionStateResponse,
        ServiceType::DisconnectRequest,
        ServiceType::DisconnectResponse,
        ServiceType::TunnellingRequest,
        ServiceType::TunnellingAck,
        ServiceType::RoutingIndication,
        ServiceType::RoutingLostMessage,
        ServiceType::RoutingBusy,
    ];

    /// The service-type identifier this variant stands for. The header
    /// carries it as 2 octets, most significant first.
    pub const fn as_u16(self) -> u16 {
        self as u16
    }
}

// `ServiceType::ALL` together with `as_u16` is now the single source of truth
// for the variant <-> discriminant mapping; decoding scans `ALL` rather than
// mirroring the discriminants in a separate table.
impl TryFrom<u16> for ServiceType {
    type Error = KnxError;

    fn try_from(value: u16) -> Result<Self> {
        ServiceType::ALL
            .iter()
            .copied()
            .find(|st| st.as_u16() == value)
            .ok_or(KnxError::UnsupportedServiceType(value))
    }
}

/// The header every KNXnet/IP frame opens with: its own length, the protocol
/// version, the service the frame is, and the length of the whole frame.
///
/// The 2 fixed octets are not held here - they are the same on every frame
/// this crate reads or writes, and [`Self::decode`] refuses a frame that
/// states either of them differently.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct KnxNetIpHeader {
    service_type: ServiceType,
    total_length: u16,
}

impl KnxNetIpHeader {
    /// Builds a header, refusing a total length that does not account for the
    /// header itself.
    ///
    /// The length a header states covers the whole frame, this header
    /// included, so a value below [`HEADER_LENGTH`] describes a frame shorter
    /// than its own head.
    pub const fn new(service_type: ServiceType, total_length: u16) -> Result<Self> {
        if total_length < HEADER_LENGTH as u16 {
            return Err(KnxError::InvalidFrame("total length shorter than header"));
        }

        Ok(Self { service_type, total_length })
    }

    /// The service this frame is.
    pub const fn service_type(self) -> ServiceType {
        self.service_type
    }

    /// The whole frame's length in octets, this header's own 6 included.
    pub const fn total_length(self) -> u16 {
        self.total_length
    }

    /// Reads a header and hands back the body that follows it, cut to the
    /// length the header states.
    ///
    /// The length octet and the version octet are checked rather than
    /// stepped over: a frame disagreeing with either is not one this crate
    /// can read, and reading on would be reading a different structure. A
    /// buffer holding less than the stated total length is refused rather
    /// than truncated, so the body handed back is the whole one or none.
    pub fn decode(input: &[u8]) -> Result<(Self, &[u8])> {
        if input.len() < HEADER_LENGTH as usize {
            return Err(KnxError::BufferTooShort {
                needed: HEADER_LENGTH as usize,
                actual: input.len(),
            });
        }

        if input[0] != HEADER_LENGTH {
            return Err(KnxError::InvalidFrame("invalid KNXnet/IP header length"));
        }
        if input[1] != PROTOCOL_VERSION_1_0 {
            return Err(KnxError::InvalidFrame("invalid KNXnet/IP protocol version"));
        }

        let service_type = ServiceType::try_from(u16::from_be_bytes([input[2], input[3]]))?;
        let total_length = u16::from_be_bytes([input[4], input[5]]);
        let header = Self::new(service_type, total_length)?;

        let total_length = usize::from(total_length);
        if input.len() < total_length {
            return Err(KnxError::BufferTooShort { needed: total_length, actual: input.len() });
        }

        Ok((header, &input[HEADER_LENGTH as usize..total_length]))
    }

    /// Appends the 6 header octets: the fixed length and version, then the
    /// service type and the total length, each most significant octet first.
    ///
    /// The total length is the one this header was built with, not a count of
    /// what follows - the caller states the frame's width before the body is
    /// appended, or measures it and builds the header afterwards.
    #[cfg(feature = "std")]
    pub fn encode(self, out: &mut std::vec::Vec<u8>) -> Result<()> {
        out.extend_from_slice(&[
            HEADER_LENGTH,
            PROTOCOL_VERSION_1_0,
            (self.service_type.as_u16() >> 8) as u8,
            self.service_type.as_u16() as u8,
            (self.total_length >> 8) as u8,
            self.total_length as u8,
        ]);
        Ok(())
    }
}

/// The transport an endpoint speaks, as the host protocol octet of an HPAI
/// names it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(u8)]
pub enum HostProtocol {
    /// IPv4 over UDP: the connectionless transport discovery and routing use,
    /// and the one where a tunnelling connection is acknowledged frame by
    /// frame because nothing underneath it orders what arrives.
    Ipv4Udp = 0x01,
    /// IPv4 over TCP: the connection-oriented transport, where the stream
    /// itself orders and retransmits what a UDP peer has to handle above the
    /// transport.
    Ipv4Tcp = 0x02,
}

// All `HostProtocol` variants in declaration order; together with `as_u8`
// this is the single source of truth for the variant <-> byte mapping.
const HOST_PROTOCOL_ALL: [HostProtocol; 2] = [HostProtocol::Ipv4Udp, HostProtocol::Ipv4Tcp];

impl HostProtocol {
    /// The host protocol code this variant stands for: the octet an HPAI
    /// carries after its own length.
    pub const fn as_u8(self) -> u8 {
        self as u8
    }
}

impl TryFrom<u8> for HostProtocol {
    type Error = KnxError;

    fn try_from(value: u8) -> Result<Self> {
        HOST_PROTOCOL_ALL
            .iter()
            .copied()
            .find(|hp| hp.as_u8() == value)
            .ok_or(KnxError::InvalidFrame("unsupported host protocol"))
    }
}

/// A Host Protocol Address Information block: the endpoint a peer is asked to
/// send to, as the sender states it.
///
/// The endpoint is stated rather than inferred from where the datagram came
/// from, which is what lets a client ask for answers on a different socket
/// than the one it asked from.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Hpai {
    protocol: HostProtocol,
    address: [u8; 4],
    port: u16,
}

impl Hpai {
    /// The block is 8 octets: its own length, the host protocol, the 4-octet
    /// IPv4 address, and the 2-octet port.
    pub const LENGTH: u8 = 0x08;

    /// Builds the block around an endpoint. Every combination of the 3 fields
    /// is expressible on the wire, so there is nothing here to refuse.
    pub const fn new(protocol: HostProtocol, address: [u8; 4], port: u16) -> Self {
        Self { protocol, address, port }
    }

    /// The transport the endpoint speaks.
    pub const fn protocol(self) -> HostProtocol {
        self.protocol
    }

    /// The 4 IPv4 address octets in the order they travel, most significant
    /// first.
    pub const fn address(self) -> [u8; 4] {
        self.address
    }

    /// The port the endpoint expects to be reached on.
    pub const fn port(self) -> u16 {
        self.port
    }

    /// Reads the block and hands back what follows it.
    ///
    /// The length octet is checked against the 8 this block always is, and a
    /// host protocol code this crate does not speak is refused rather than
    /// carried: an endpoint whose transport is unknown is one nothing can be
    /// sent to.
    pub fn decode(input: &[u8]) -> Result<(Self, &[u8])> {
        if input.len() < Self::LENGTH as usize {
            return Err(KnxError::BufferTooShort {
                needed: Self::LENGTH as usize,
                actual: input.len(),
            });
        }
        if input[0] != Self::LENGTH {
            return Err(KnxError::InvalidFrame("invalid HPAI length"));
        }

        let protocol = HostProtocol::try_from(input[1])?;
        let address = [input[2], input[3], input[4], input[5]];
        let port = u16::from_be_bytes([input[6], input[7]]);

        Ok((Self::new(protocol, address, port), &input[Self::LENGTH as usize..]))
    }

    /// Appends the 8 block octets: the fixed length, the protocol code, the
    /// address, and the port most significant octet first.
    #[cfg(feature = "std")]
    pub fn encode(self, out: &mut std::vec::Vec<u8>) -> Result<()> {
        out.extend_from_slice(&[
            Self::LENGTH,
            self.protocol.as_u8(),
            self.address[0],
            self.address[1],
            self.address[2],
            self.address[3],
            (self.port >> 8) as u8,
            self.port as u8,
        ]);
        Ok(())
    }
}

/// The Connection Response Data a tunnelling CONNECT_RESPONSE carries.
///
/// A server hands every tunnelling connection it accepts an individual
/// address of its own, and this block is where it states it. Skipping
/// the block leaves a client with no address to stamp on the frames it
/// sends and no way to recognise its own traffic among what the bus
/// reports, so the address is parsed rather than discarded.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct TunnellingCrd {
    address: IndividualAddress,
}

impl TunnellingCrd {
    /// The block is 4 octets: its own length, the connection type, and
    /// the 2-octet address.
    pub const LENGTH: u8 = 0x04;

    /// The connection-type code a tunnelling connection states.
    pub const CONNECTION_TYPE: u8 = 0x04;

    /// Builds the block around the address a server assigned. Every
    /// individual address is expressible here, so there is nothing to refuse.
    pub const fn new(address: IndividualAddress) -> Self {
        Self { address }
    }

    /// The individual address the server assigned to this connection.
    pub const fn address(self) -> IndividualAddress {
        self.address
    }

    /// Reads the block, refusing one that is not a tunnelling CRD.
    ///
    /// The connection type is checked rather than assumed: the same
    /// position carries a different block for every other connection
    /// type, and reading one of those as an address would report a
    /// number that is not an address at all.
    pub fn decode(input: &[u8]) -> Result<(Self, &[u8])> {
        if input.len() < Self::LENGTH as usize {
            return Err(KnxError::BufferTooShort {
                needed: Self::LENGTH as usize,
                actual: input.len(),
            });
        }
        if input[0] != Self::LENGTH {
            return Err(KnxError::InvalidFrame("invalid tunnelling CRD length"));
        }
        if input[1] != Self::CONNECTION_TYPE {
            return Err(KnxError::InvalidFrame("connection response data is not a tunnelling CRD"));
        }

        Ok((
            Self::new(IndividualAddress::from_raw(u16::from_be_bytes([input[2], input[3]]))),
            &input[Self::LENGTH as usize..],
        ))
    }

    /// Appends the 4 block octets: the fixed length, the tunnelling
    /// connection type, and the assigned address most significant octet
    /// first.
    #[cfg(feature = "std")]
    pub fn encode(self, out: &mut std::vec::Vec<u8>) -> Result<()> {
        out.extend_from_slice(&[
            Self::LENGTH,
            Self::CONNECTION_TYPE,
            (self.address.raw() >> 8) as u8,
            self.address.raw() as u8,
        ]);
        Ok(())
    }
}

/// The header a frame on an established connection carries ahead of its
/// payload: which channel it belongs to, and where it sits in that channel's
/// sequence.
///
/// A tunnelling connection is ordered by this header rather than by the
/// transport underneath it, which is why the sequence number travels with
/// every frame and comes back on the acknowledgement.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct ConnectionHeader {
    channel_id: u8,
    sequence_counter: u8,
    status: u8,
}

impl ConnectionHeader {
    /// The header is 4 octets: its own length, the channel id, the sequence
    /// counter, and the status.
    pub const LENGTH: u8 = 0x04;

    /// Builds the header. Each field is a single octet this crate places as
    /// given, so there is nothing here to refuse.
    pub const fn new(channel_id: u8, sequence_counter: u8, status: u8) -> Self {
        Self { channel_id, sequence_counter, status }
    }

    /// The channel this frame belongs to, as the server numbered it when it
    /// accepted the connection.
    pub const fn channel_id(self) -> u8 {
        self.channel_id
    }

    /// Where this frame sits in the channel's sequence. The acknowledgement
    /// that answers it names the same number, which is what ties the 2
    /// together.
    pub const fn sequence_counter(self) -> u8 {
        self.sequence_counter
    }

    /// The status octet as it arrived, reported rather than interpreted. A
    /// request states 0 here; an acknowledgement states the outcome, and
    /// those codes are not modeled by this crate.
    pub const fn status(self) -> u8 {
        self.status
    }

    /// Reads the header and hands back the payload that follows it.
    ///
    /// The length octet is checked against the 4 this header always is; the
    /// channel, sequence, and status octets carry no value this layer
    /// refuses, so whether the frame is one the reader wanted is the caller's
    /// question.
    pub fn decode(input: &[u8]) -> Result<(Self, &[u8])> {
        if input.len() < Self::LENGTH as usize {
            return Err(KnxError::BufferTooShort {
                needed: Self::LENGTH as usize,
                actual: input.len(),
            });
        }
        if input[0] != Self::LENGTH {
            return Err(KnxError::InvalidFrame("invalid connection header length"));
        }

        Ok((Self::new(input[1], input[2], input[3]), &input[Self::LENGTH as usize..]))
    }

    /// Appends the 4 header octets: the fixed length, the channel id, the
    /// sequence counter, and the status.
    #[cfg(feature = "std")]
    pub fn encode(self, out: &mut std::vec::Vec<u8>) -> Result<()> {
        out.extend_from_slice(&[Self::LENGTH, self.channel_id, self.sequence_counter, self.status]);
        Ok(())
    }
}