utl/include/utl/com/_1wire_uart.h

/*!
 * \file    utl/com/_1wire_uart.h
 * \brief
 *    A 1-wire implementation using a microprocessor's uart for bit timing
 * \note
 *    This 1-wire implementation is based on MCU UART io functionality. In order
 *    to work it needs:
 *    1) A Open drain tx and floating(or pull-up) rx UART pin configuration with both pins
 *       connected to the 1-wire bus wire
 *    2) A Transmit/receive function even in blocking/polling mode
 *    3) A baudrate set function
 *
 * Copyright (C) 2018 Christos Choutouridis
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation, either version 3
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 */
#ifndef __utl_com_1wire_uart_h__
#define __utl_com_1wire_uart_h__

#include <utl/impl/impl.h>
#include <utl/helper/crtp.h>
#include <utl/com/_1wire.h>

namespace utl {
/*!
 * \ingroup Communication
 * A 1-wire implementation using a microprocessor's uart for bit timing
 * inherited from \ref _1wire_i base class.
 * \sa   _1wire_i
 */
//!@{

   /*!
   * \brief
   *    1-wire UART interface template class using CRTP
   * Using the private virtual interface we provide the interface from
   * _1wire_i<>
   */
  template <typename Impl_t>
  class _1wire_uart_i : public _1wire_i<_1wire_uart_i<Impl_t>> {
     _CRTP_IMPL(Impl_t);   //! \brief  Syntactic sugar to CRTP casting
     friend _1wire_i <_1wire_uart_i<Impl_t>>;
  public:
     using type    = _1wire_uart_i<Impl_t>;          //!< Export type as identity meta-function
     using Speed   = typename _1wire_i<type>::Speed; //!< Bring bus speed

  /*!
   * \name Object lifetime
   */
  //!@{
  protected:
      _1wire_uart_i () = default;   //!< Allow constructor from derived only
      ~_1wire_uart_i () = default;  //!< Allow destructor from derived only
  //!@}

  /*!
   * \name Implementation requirements
   * \note
   *    In order for the implementation to have the following as private members
   *    it also need to declare this class as friend
   *    for ex:
   *    class Foo : public _1wire_uart<Foo> {
   *       friend _1wire_uart<Foo>;
   *       byte_t UART_RW (byte_t byte);
   *       void UART_BR (uint32_t br);
   *       // ...
   *    };
   */
  //!@{
  private:
     /*!
      * \brief
      *    Implementers's (driver) read-write function. We use the following USART configuration.
      *       - Word Length = 8 Bits
      *       - Stop Bit    = One Stop bit
      *       - Parity      = No parity
      * \param   The byte to send
      * \return  The byte received.
      * \note
      *    Due to the nature of the technique, the received byte is the actual bus
      *    condition during the communication frame (time slot)
      */
     byte_t UART_RW (byte_t byte) { return impl().UART_RW (byte); }

     /*!
      * \brief
      *    Implementers's (driver) baudrate function.
      * \param   The desired Baudrate
      */
     void UART_BR (uint32_t br) { impl().UART_BR (br); }
  //!@}

  //! \name Implementation of base requirements
  //!@{
  private:
     //! 1-wire UART baudrates
     enum BR {
        BR_STD_RST  =9600,
        BR_OVR_RST  =57600,
        BR_STD      =115200,
        BR_OVR      =921600
     };
     Speed     _speed {Speed::STD};

     Speed speed ()       { return _speed; }   //!< Get the 1-wire bus speed
     void speed (Speed s);  //!< Set the 1-wire bus speed

     /*!
      * \brief
      *    Read a bit from the 1-Wire bus, return it and provide
      *    the recovery time.
      *
      *           ---       - - - - - - - - - - - - - - - - ------
      * Read         \     / X X X X X X X X X X X X X X X /
      *               ----  - - - - - - - - - - - - - - - -
      *  RS:          |   |   |   |   |   |   |   |   |   |   |
      *  bit:          ST   0   1   2   3   4   5   6   7   SP
      *               < ------------- 87/11 usec ------------->
      *                     ^
      *                     |
      *                Master sample
      *
      *  8 bits, no parity, 1 stop
      *  standard:  BR: 115200
      *  Overdrive: BR: 921600
      *  TX: 0xFF
      *  RX: {1 - 0xFF,   0 - [0x00 - 0xFE] }
      *
      * \return  The answer
      *    \arg  0  Read 0
      *    \arg  1  Read 1 (This is also returned on transition error).
      */
     bool bit () {
        return (impl().UART_RW (0xFF) < 0xFF);
     }


     /*!
      * \brief
      *    Send a 1-Wire write bit
      * 8 bits, no parity, 1 stop
      * standard:  BR: 115200
      * Overdrive: BR: 921600
      *
      *           ---       --------------------------------------
      * Write 1      \     /
      *               ----
      *  RS:          |   |   |   |   |   |   |   |   |   |   |
      *  bit:          ST   0   1   2   3   4   5   6   7   SP
      *  TX: 0xFF      RX: 0xFF
      *
      *           ---                                       ------
      * Write 0      \                                     /
      *               -------------------------------------
      *  RS:          |   |   |   |   |   |   |   |   |   |   |
      *  bit:          ST   0   1   2   3   4   5   6   7   SP
      *               < ------------- 87/11 usec ------------->
      *  TX: 0x00      RX: 0x00
      *
      * \param   b     The bit to send
      * \return        Status of the operation
      *    \arg  0     Fail
      *    \arg  1     Success
      */
     bool bit (bool b) {
        uint8_t w = (b) ? 0xFF : 0x00;      // Select write frame to send
        return (w == impl().UART_RW (w));   // Return status
     }
     bool _reset ();
  //!@}
  };

  /*!
   * Set the 1-wire bus speed for normal operation only
   * \note
   *    We have moved the BR set functionality here to reduce the code inside bit().
   *    This is OK as long as the _1wire_i<> always check speed.
   * \param s    The desired speed
   */
  template <typename Impl_t>
  void _1wire_uart_i<Impl_t>::speed (Speed s) {
     switch (_speed = s) {
        case Speed::STD:   impl().UART_BR (BR_STD); break;
        case Speed::OVDR:  impl().UART_BR (BR_OVR); break;
     }
  }

  /*!
   * \brief
   *    Generate a 1-wire reset
   *
   *           ---                      ----  -  -  -  -------
   * Reset        \                    /    \ X  X  X /
   *               --------------------      -  -  - -
   *  RS:          |   |   |   |   |   |   |   |   |   |   |
   *  bit:          ST   0   1   2   3   4   5   6   7   SP
   *               < ---------- 1024/174 usec ------------->
   *
   *  8 bits, no parity, 1 stop
   *  Standard:                          Overdrive :
   *  BR: 9600,                          BR: 57600
   *  TX: 0xF0,                          TX: 0xF8
   *  RX: 0xF0 not present               RX: 0xF8 not present
   *      less if present                    less if present
   *
   * \param   t  Timing
   * \return  The status of the operation
   *    \arg  0  Fail
   *    \arg  1  Success
   */
  template <typename Impl_t>
  bool _1wire_uart_i<Impl_t>::_reset () {
     // Select frame to send
     uint8_t   w = (_speed == Speed::STD) ? 0xF0 : 0xF8;
     // Select baudrate
     impl().UART_BR ((_speed == Speed::STD) ? BR_STD_RST : BR_OVR_RST);
     // Send frame and check the result
     return (impl().UART_RW (w) < w);
  }

   /*!
    * \brief
    *    A virtual base class interface implementation.
    * Using the private virtual interface we provide the interface from
    * _1wire_i<virtual_tag>
    * \param   impl_t = virtual_tag
    */
   template <>
   class _1wire_uart_i<virtual_tag> : public _1wire_i<virtual_tag> {
   public:
      using type    = _1wire_uart_i<virtual_tag>;              //!< Export type as identity meta-function
      using Speed   = typename _1wire_i<virtual_tag>::Speed;   //!< Bring bus speed

   /*!
    * \name Object lifetime
    */
   //!@{
   protected:
      _1wire_uart_i () = default;   //!< Allow constructor from derived only
      ~_1wire_uart_i () = default;  //!< Allow destructor from derived only
   //!@}

   /*!
    * \name Implementation requirements
    */
   //!@{
   private:
      /*!
       * \brief
       *    Implementers's (driver) read-write function. We use the following USART configuration.
       *       - Word Length = 8 Bits
       *       - Stop Bit    = One Stop bit
       *       - Parity      = No parity
       * \param   The byte to send
       * \return  The byte received.
       * \note
       *    Due to the nature of the technique, the received byte is the actual bus
       *    condition during the communication frame (time slot)
       */
      virtual byte_t UART_RW (byte_t byte) =0;

      /*!
       * \brief
       *    Implementers's (driver) baudrate function.
       * \param   The desired Baudrate
       */
      virtual void UART_BR (uint32_t br) =0;
   //!@}

   //! \name Implementation of base requirements
   //!@{
   private:
      //! 1-wire UART baudrates
      enum BR {
         BR_STD_RST  =9600,
         BR_OVR_RST  =57600,
         BR_STD      =115200,
         BR_OVR      =921600
      };
      Speed _speed {Speed::STD};

      Speed speed () { return _speed; }   //!< Get the 1-wire bus speed
      void speed (Speed s);               //!< Set the 1-wire bus speed

      /*!
       * \brief
       *    Read a bit from the 1-Wire bus, return it and provide
       *    the recovery time.
       *
       *           ---       - - - - - - - - - - - - - - - - ------
       * Read         \     / X X X X X X X X X X X X X X X /
       *               ----  - - - - - - - - - - - - - - - -
       *  RS:          |   |   |   |   |   |   |   |   |   |   |
       *  bit:          ST   0   1   2   3   4   5   6   7   SP
       *               < ------------- 87/11 usec ------------->
       *                     ^
       *                     |
       *                Master sample
       *
       *  8 bits, no parity, 1 stop
       *  standard:  BR: 115200
       *  Overdrive: BR: 921600
       *  TX: 0xFF
       *  RX: {1 - 0xFF,   0 - [0x00 - 0xFE] }
       *
       * \return  The answer
       *    \arg  0  Read 0
       *    \arg  1  Read 1 (This is also returned on transition error).
       */
      bool bit () {
         return (UART_RW (0xFF) < 0xFF);
      }


      /*!
       * \brief
       *    Send a 1-Wire write bit
       * 8 bits, no parity, 1 stop
       * standard:  BR: 115200
       * Overdrive: BR: 921600
       *
       *           ---       --------------------------------------
       * Write 1      \     /
       *               ----
       *  RS:          |   |   |   |   |   |   |   |   |   |   |
       *  bit:          ST   0   1   2   3   4   5   6   7   SP
       *  TX: 0xFF      RX: 0xFF
       *
       *           ---                                       ------
       * Write 0      \                                     /
       *               -------------------------------------
       *  RS:          |   |   |   |   |   |   |   |   |   |   |
       *  bit:          ST   0   1   2   3   4   5   6   7   SP
       *               < ------------- 87/11 usec ------------->
       *  TX: 0x00      RX: 0x00
       *
       * \param   b     The bit to send
       * \return        Status of the operation
       *    \arg  0     Fail
       *    \arg  1     Success
       */
      bool bit (bool b) {
         uint8_t w = (b) ? 0xFF : 0x00;   // Select write frame to send
         return (w == UART_RW (w));       // Return status
      }
      bool _reset ();
   //!@}
   };

   /*!
    * Set the 1-wire bus speed for normal operation only
    * \note
    *    We have moved the BR set functionality here to reduce the code inside bit().
    *    This is OK as long as the _1wire_i<> always check speed.
    * \param s    The desired speed
    */
   void _1wire_uart_i<virtual_tag>::speed (Speed s) {
      switch (_speed = s) {
         case Speed::STD:  UART_BR (BR_STD); break;
         case Speed::OVDR: UART_BR (BR_OVR); break;
      }
   }

   /*!
    * \brief
    *    Generate a 1-wire reset
    *
    *           ---                      ----  -  -  -  -------
    * Reset        \                    /    \ X  X  X /
    *               --------------------      -  -  - -
    *  RS:          |   |   |   |   |   |   |   |   |   |   |
    *  bit:          ST   0   1   2   3   4   5   6   7   SP
    *               < ---------- 1024/174 usec ------------->
    *
    *  8 bits, no parity, 1 stop
    *  Standard:                          Overdrive :
    *  BR: 9600,                          BR: 57600
    *  TX: 0xF0,                          TX: 0xF8
    *  RX: 0xF0 not present               RX: 0xF8 not present
    *      less if present                    less if present
    *
    * \param   t  Timing
    * \return  The status of the operation
    *    \arg  0  Fail
    *    \arg  1  Success
    */
   bool _1wire_uart_i<virtual_tag>::_reset () {
      // Select frame to send
      uint8_t   w = (_speed == Speed::STD) ? 0xF0 : 0xF8;
      // Select baudrate
      UART_BR ((_speed == Speed::STD) ? BR_STD_RST : BR_OVR_RST);
      // Send frame and check the result
      return (UART_RW (w) < w);
   }

//!@}

}  // namespace utl

#endif /* __utl_com_1wire_uart_h__ */