import abc
from typing import Optional


class LowLevelHardwareInterface(metaclass=abc.ABCMeta):
    """Low level interface for hardware.
    It provide the general *send* / *read* interface to control/communicate with the hardware.

    **low level function**

    1. :func:`send_byte`
    #. :func:`recv_byte`

    **helper function**

    implicit use ``struct`` to help pack/unpack data to/from raw byte data.

    1. :func:`send_data`
    #. :func:`recv_data`

    """

    __slots__ = ()

    @abc.abstractmethod
    def reset(self):
        """reset hardware. and go to configuration state.
        Otherwise, raise RuntimeError.
        """
        pass

    @abc.abstractmethod
    def close(self):
        """close hardware. reject all following action, instruction and command."""
        pass

    @abc.abstractmethod
    def flush(self):
        """flush the command buffer. return when the hardware state at the correct state."""
        pass

    @abc.abstractmethod
    def send_byte(self, data: bytes):
        """send raw byte instruction to the hardware

        .. seealso:: :func:`send_data`

        :param data: raw byte instruction
        """
        pass

    @abc.abstractmethod
    def recv_byte(self, size: int) -> Optional[bytes]:
        """receive raw byte data from hardware.

        .. seealso:: :func:`recv_data`

        :param size: number of bytes want to receive
        :return: raw byte data, None if fail.
        """
        pass