/firmware/src/Motherboard/Tool.hh

  1/*
  2 * Copyright 2010 by Adam Mayer	 <adam@makerbot.com>
  3 *
  4 * This program is free software: you can redistribute it and/or modify
  5 * it under the terms of the GNU General Public License as published by
  6 * the Free Software Foundation, either version 3 of the License, or
  7 * (at your option) any later version.
  8 *
  9 * This program is distributed in the hope that it will be useful,
 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 12 * GNU General Public License for more details.
 13 *
 14 * You should have received a copy of the GNU General Public License
 15 * along with this program.  If not, see <http://www.gnu.org/licenses/>
 16 */
 17
 18#ifndef TOOL_HH_
 19#define TOOL_HH_
 20
 21#include "Packet.hh"
 22
 23// TODO: Make this into a class.
 24
 25/// There are three fundamental ways to initiate a tool interaction.  They are:
 26/// <ul>
 27/// <li> Passthrough queries.  These are initiated by the host.  The controller passes
 28///      the query along to the tool, and the response is copied back to the host.</li>
 29/// <li> Controller queries.  These are initiated by the controller.  They generally
 30///      are not directly returned to the host.</li>
 31/// <li> Queued commands.  The responses from these queries are generally discarded.
 32///     At this time, the command thread blocks until these commands return.</li>
 33/// </ul>
 34///
 35/// Because the tool can only process one transaction at a time, and we don't
 36/// want to block on tool transactions, the tool lock must be acquired before using
 37/// the tool interface. Once the lock is acquired, it must be explicitly released by
 38/// the holder.
 39namespace tool {
 40
 41/// Run the tool maintenance timeslice.  Checks for tool command timeouts, etc.
 42void runToolSlice();
 43
 44/// Get the tool interaction lock.
 45/// \return True if the lock has been successfully acquired, false otherwise.
 46bool getLock();
 47
 48/// Release the tool interaction lock, letting some other part of the system
 49/// interact with the toolheads.
 50void releaseLock();
 51
 52/// Start a transaction.  Assumes that the caller has acquired the lock and
 53/// filled the output packet.
 54void startTransaction();
 55
 56/// Check if the transaction is completed.
 57/// \return True if the transaction is complete.
 58bool isTransactionDone();
 59
 60/// Get the output packet
 61/// \return Reference to the output packet, which the host should fill with a query
 62///         to send to the tool.
 63OutPacket& getOutPacket();
 64
 65/// Get the input packet
 66/// \return Reference to the input packet, which should contain a query respose from
 67///         the tool, which the host should then inspect.
 68InPacket& getInPacket();
 69
 70/// Get the total number of packets that were attempted to be sent to a tool. This can
 71/// be used to assess communication quality with the tool.
 72/// \return Total number of packets sent over the rs485 line to the tool
 73uint32_t getSentPacketCount();
 74
 75/// Get the total number of packets that failed to get a response from a tool. This can
 76/// be used to assess communication quality with the tool.
 77/// \return Total number of packets sent to the tool, that failed to generate a response.
 78uint32_t getPacketFailureCount();
 79
 80/// Get the total packet retries attempted. The host will attempt to retry a packet 5 times
 81/// before giving up, so this number will increase by 5 for every failed packet.
 82/// \return Total number of packet retries attempted.
 83uint32_t getRetryCount();
 84
 85/// Get the total number of received bytes that were discarded as noise.
 86/// \return Total number of noise bytes received.
 87uint32_t getNoiseByteCount();
 88
 89/// Attempt to reset the tool by sending it a reset packet
 90/// \return True if the extruder responded to the reset request.
 91bool reset();
 92
 93/// Attempt to test the tool by sending it a series of pings
 94/// \return True if the test succeeded; false otherwise.
 95bool test();
 96
 97/// Set the toolhead index
 98/// \param index Index (0-127) of the toolhead to communicate with
 99void setCurrentToolheadIndex(uint8_t index);
100
101/// Get the current toolhead index
102/// \return Index of the current toolhead.
103uint8_t getCurrentToolheadIndex();
104
105}
106
107#endif // TOOL_HH_