marlin/Marlin/twibus.h

/*
 * Marlin 3D Printer Firmware
 * Copyright (C) 2016 MarlinFirmware [https://github.com/MarlinFirmware/Marlin]
 *
 * Based on Sprinter and grbl.
 * Copyright (C) 2011 Camiel Gubbels / Erik van der Zalm
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU 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 General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 */

#ifndef TWIBUS_H
#define TWIBUS_H

#include "macros.h"

#include <Wire.h>

// Print debug messages with M111 S2 (Uses 236 bytes of PROGMEM)
//#define DEBUG_TWIBUS

typedef void (*twiSlaveFunc_t)(int bytes);

/**
 * TWIBUS class
 *
 * This class implements a wrapper around the two wire (I2C) bus, it allows
 * Marlin to send and request data from any slave device on the bus. This is
 * an experimental feature and it's inner workings as well as public facing
 * interface are prune to change in the future.
 *
 * The two main consumers of this class are M155 and M156, where M155 allows
 * Marlin to send a I2C packet to a device (please be aware that no repeated
 * starts are possible), this can be done in caching method by calling multiple
 * times M155 B<byte-1 value in base 10> or a one liner M155, have a look at
 * the gcode_M155() function for more information. M156 allows Marlin to
 * request data from a device, the received data is then relayed into the serial
 * line for host interpretation.
 *
 */
class TWIBus {
  private:
    /**
     * @brief Timeout value in milliseconds
     * @details Maximum amount of time (ms) to wait for a reply.
     *          Useful if something goes wrong on the bus and the
     *          SDA/SCL lines are held up by another device.
     */
    const int timeout = 5;

    /**
     * @brief Number of bytes on buffer
     * @description Number of bytes in the buffer waiting to be flushed to the bus.
     */
    uint8_t buffer_s = 0;

    /**
     * @brief Internal buffer
     * @details A fixed buffer. TWI commands can be no longer than this.
     */
    char buffer[32];


  public:
    /**
     * @brief Target device address
     * @description The target device address. Persists until changed.
     */
    uint8_t addr = 0;

    /**
     * @brief Class constructor
     * @details Initialize the TWI bus and clear the buffer
     */
    TWIBus();

    /**
     * @brief Reset the buffer
     * @details Set the buffer to a known-empty state
     */
    void reset();

    /**
     * @brief Send the buffer data to the bus
     * @details Flush the buffer to the bus at the target address.
     */
    void send();

    /**
     * @brief Add one byte to the buffer
     * @details Add a byte to the end of the buffer.
     *          Silently fails if the buffer is full.
     *
     * @param c a data byte
     */
    void addbyte(const char c);

    /**
     * @brief Set the target slave address
     * @details The target slave address for sending the full packet.
     *
     * @param addr 7-bit integer address
     */
    void address(const uint8_t addr);

    /**
     * @brief Request data from the slave device
     * @details Request a number of bytes from a slave device.
     *          This implementation simply sends the data to serial
     *          in a parser-friendly format.
     *
     * @param bytes the number of bytes to request
     */
    void reqbytes(const uint8_t bytes);

    /**
     * @brief Relay data from the slave device to serial
     * @details Relay a number of bytes from the bus to
     *          serial in a parser-friendly format.
     *
     * @param bytes the number of bytes to request
     */
    void relaydata(uint8_t bytes);

    #if I2C_SLAVE_ADDRESS > 0

      /**
       * @brief Receive bytes (passively)
       * @details Receive bytes sent to our slave address.
       *          and simply echo them to serial.
       */
      inline void receive(uint8_t bytes) { relaydata(bytes); }

      /**
       * @brief Register a slave handler
       * @details Set a handler to receive data from the bus,
       *          so we can act as a slave.
       *
       * @param handler A function to handle receiving bytes
       */
      inline void onReceive(const twiSlaveFunc_t handler) { Wire.onReceive(handler); }

    #endif

    #if ENABLED(DEBUG_TWIBUS)

      /**
       * @brief Prints a debug message
       * @details Prints a simple debug message "TWIBus::function: value"
       */
      static void debug(const char func[], int32_t val = -1);

    #endif
};

#endif //TWIBUS_H