ilkay KOZAK / RadioHead-148

V148

Fork of RadioHead-148 by David Rimer

RHDatagram.h@1:b7641da2b203, 2017-10-25 (annotated)

Committer:
ilkaykozak
Date:
Wed Oct 25 05:14:09 2017 +0000
Revision:
1:b7641da2b203
Parent:
0:ab4e012489ef 
V148

Who changed what in which revision?

UserRevisionLine numberNew contents of line
davidr99 0:ab4e012489ef 1 // RHDatagram.h
davidr99 0:ab4e012489ef 2 // Author: Mike McCauley (mikem@airspayce.com)
davidr99 0:ab4e012489ef 3 // Copyright (C) 2011 Mike McCauley
davidr99 0:ab4e012489ef 4 // $Id: RHDatagram.h,v 1.14 2015/08/12 23:18:51 mikem Exp $
davidr99 0:ab4e012489ef 5
davidr99 0:ab4e012489ef 6 #ifndef RHDatagram_h
davidr99 0:ab4e012489ef 7 #define RHDatagram_h
davidr99 0:ab4e012489ef 8
davidr99 0:ab4e012489ef 9 #include <RHGenericDriver.h>
davidr99 0:ab4e012489ef 10
davidr99 0:ab4e012489ef 11 // This is the maximum possible message size for radios supported by RadioHead.
davidr99 0:ab4e012489ef 12 // Not all radios support this length, and many are much smaller
davidr99 0:ab4e012489ef 13 #define RH_MAX_MESSAGE_LEN 255
davidr99 0:ab4e012489ef 14
davidr99 0:ab4e012489ef 15 /////////////////////////////////////////////////////////////////////
davidr99 0:ab4e012489ef 16 /// \class RHDatagram RHDatagram.h <RHDatagram.h>
davidr99 0:ab4e012489ef 17 /// \brief Manager class for addressed, unreliable messages
davidr99 0:ab4e012489ef 18 ///
davidr99 0:ab4e012489ef 19 /// Every RHDatagram node has an 8 bit address (defaults to 0).
davidr99 0:ab4e012489ef 20 /// Addresses (DEST and SRC) are 8 bit integers with an address of RH_BROADCAST_ADDRESS (0xff)
davidr99 0:ab4e012489ef 21 /// reserved for broadcast.
davidr99 0:ab4e012489ef 22 ///
davidr99 0:ab4e012489ef 23 /// \par Media Access Strategy
davidr99 0:ab4e012489ef 24 ///
davidr99 0:ab4e012489ef 25 /// RHDatagram and the underlying drivers always transmit as soon as sendto() is called.
davidr99 0:ab4e012489ef 26 ///
davidr99 0:ab4e012489ef 27 /// \par Message Lengths
davidr99 0:ab4e012489ef 28 ///
davidr99 0:ab4e012489ef 29 /// Not all Radio drivers supported by RadioHead can handle the same message lengths. Some radios can handle
davidr99 0:ab4e012489ef 30 /// up to 255 octets, and some as few as 28. If you attempt to send a message that is too long for
davidr99 0:ab4e012489ef 31 /// the underlying driver, sendTo() will return false and will not transmit the message.
davidr99 0:ab4e012489ef 32 /// It is the programmers responsibility to make
davidr99 0:ab4e012489ef 33 /// sure that messages passed to sendto() do not exceed the capability of the radio. You can use the
davidr99 0:ab4e012489ef 34 /// *_MAX_MESSAGE_LENGTH definitions or driver->maxMessageLength() to help.
davidr99 0:ab4e012489ef 35 ///
davidr99 0:ab4e012489ef 36 /// \par Headers
davidr99 0:ab4e012489ef 37 ///
davidr99 0:ab4e012489ef 38 /// Each message sent and received by a RadioHead driver includes 4 headers:<br>
davidr99 0:ab4e012489ef 39 /// \b TO The node address that the message is being sent to (broadcast RH_BROADCAST_ADDRESS (255) is permitted)<br>
davidr99 0:ab4e012489ef 40 /// \b FROM The node address of the sending node<br>
davidr99 0:ab4e012489ef 41 /// \b ID A message ID, distinct (over short time scales) for each message sent by a particilar node<br>
davidr99 0:ab4e012489ef 42 /// \b FLAGS A bitmask of flags. The most significant 4 bits are reserved for use by RadioHead. The least
davidr99 0:ab4e012489ef 43 /// significant 4 bits are reserved for applications.<br>
davidr99 0:ab4e012489ef 44 ///
davidr99 0:ab4e012489ef 45 class RHDatagram
davidr99 0:ab4e012489ef 46 {
davidr99 0:ab4e012489ef 47 public:
davidr99 0:ab4e012489ef 48 /// Constructor.
davidr99 0:ab4e012489ef 49 /// \param[in] driver The RadioHead driver to use to transport messages.
davidr99 0:ab4e012489ef 50 /// \param[in] thisAddress The address to assign to this node. Defaults to 0
davidr99 0:ab4e012489ef 51 RHDatagram(RHGenericDriver& driver, uint8_t thisAddress = 0);
davidr99 0:ab4e012489ef 52
davidr99 0:ab4e012489ef 53 /// Initialise this instance and the
davidr99 0:ab4e012489ef 54 /// driver connected to it.
davidr99 0:ab4e012489ef 55 bool init();
davidr99 0:ab4e012489ef 56
davidr99 0:ab4e012489ef 57 /// Sets the address of this node. Defaults to 0.
davidr99 0:ab4e012489ef 58 /// This will be used to set the FROM address of all messages sent by this node.
davidr99 0:ab4e012489ef 59 /// In a conventional multinode system, all nodes will have a unique address
davidr99 0:ab4e012489ef 60 /// (which you could store in EEPROM).
davidr99 0:ab4e012489ef 61 /// \param[in] thisAddress The address of this node
davidr99 0:ab4e012489ef 62 void setThisAddress(uint8_t thisAddress);
davidr99 0:ab4e012489ef 63
davidr99 0:ab4e012489ef 64 /// Sends a message to the node(s) with the given address
davidr99 0:ab4e012489ef 65 /// RH_BROADCAST_ADDRESS is a valid address which will cause the message
davidr99 0:ab4e012489ef 66 /// to be accepted by all RHDatagram nodes within range.
davidr99 0:ab4e012489ef 67 /// \param[in] buf Pointer to the binary message to send
davidr99 0:ab4e012489ef 68 /// \param[in] len Number of octets to send (> 0)
davidr99 0:ab4e012489ef 69 /// \param[in] address The address to send the message to.
davidr99 0:ab4e012489ef 70 /// \return true if the message not too loing fot eh driver, and the message was transmitted.
davidr99 0:ab4e012489ef 71 bool sendto(uint8_t* buf, uint8_t len, uint8_t address);
davidr99 0:ab4e012489ef 72
davidr99 0:ab4e012489ef 73 /// Turns the receiver on if it not already on.
davidr99 0:ab4e012489ef 74 /// If there is a valid message available for this node, copy it to buf and return true
davidr99 0:ab4e012489ef 75 /// The SRC address is placed in *from if present and not NULL.
davidr99 0:ab4e012489ef 76 /// The DEST address is placed in *to if present and not NULL.
davidr99 0:ab4e012489ef 77 /// If a message is copied, *len is set to the length.
davidr99 0:ab4e012489ef 78 /// You should be sure to call this function frequently enough to not miss any messages
davidr99 0:ab4e012489ef 79 /// It is recommended that you call it in your main loop.
davidr99 0:ab4e012489ef 80 /// \param[in] buf Location to copy the received message
davidr99 0:ab4e012489ef 81 /// \param[in,out] len Pointer to available space in buf. Set to the actual number of octets copied.
davidr99 0:ab4e012489ef 82 /// \param[in] from If present and not NULL, the referenced uint8_t will be set to the FROM address
davidr99 0:ab4e012489ef 83 /// \param[in] to If present and not NULL, the referenced uint8_t will be set to the TO address
davidr99 0:ab4e012489ef 84 /// \param[in] id If present and not NULL, the referenced uint8_t will be set to the ID
davidr99 0:ab4e012489ef 85 /// \param[in] flags If present and not NULL, the referenced uint8_t will be set to the FLAGS
davidr99 0:ab4e012489ef 86 /// (not just those addressed to this node).
davidr99 0:ab4e012489ef 87 /// \return true if a valid message was copied to buf
davidr99 0:ab4e012489ef 88 bool recvfrom(uint8_t* buf, uint8_t* len, uint8_t* from = NULL, uint8_t* to = NULL, uint8_t* id = NULL, uint8_t* flags = NULL);
davidr99 0:ab4e012489ef 89
davidr99 0:ab4e012489ef 90 /// Tests whether a new message is available
davidr99 0:ab4e012489ef 91 /// from the Driver.
davidr99 0:ab4e012489ef 92 /// On most drivers, this will also put the Driver into RHModeRx mode until
davidr99 0:ab4e012489ef 93 /// a message is actually received bythe transport, when it will be returned to RHModeIdle.
davidr99 0:ab4e012489ef 94 /// This can be called multiple times in a timeout loop.
davidr99 0:ab4e012489ef 95 /// \return true if a new, complete, error-free uncollected message is available to be retreived by recv()
davidr99 0:ab4e012489ef 96 bool available();
davidr99 0:ab4e012489ef 97
davidr99 0:ab4e012489ef 98 /// Starts the Driver receiver and blocks until a valid received
davidr99 0:ab4e012489ef 99 /// message is available.
davidr99 0:ab4e012489ef 100 void waitAvailable();
davidr99 0:ab4e012489ef 101
davidr99 0:ab4e012489ef 102 /// Blocks until the transmitter
davidr99 0:ab4e012489ef 103 /// is no longer transmitting.
davidr99 0:ab4e012489ef 104 bool waitPacketSent();
davidr99 0:ab4e012489ef 105
davidr99 0:ab4e012489ef 106 /// Blocks until the transmitter is no longer transmitting.
davidr99 0:ab4e012489ef 107 /// or until the timeout occuers, whichever happens first
davidr99 0:ab4e012489ef 108 /// \param[in] timeout Maximum time to wait in milliseconds.
davidr99 0:ab4e012489ef 109 /// \return true if the radio completed transmission within the timeout period. False if it timed out.
davidr99 0:ab4e012489ef 110 bool waitPacketSent(uint16_t timeout);
davidr99 0:ab4e012489ef 111
davidr99 0:ab4e012489ef 112 /// Starts the Driver receiver and blocks until a received message is available or a timeout
davidr99 0:ab4e012489ef 113 /// \param[in] timeout Maximum time to wait in milliseconds.
davidr99 0:ab4e012489ef 114 /// \return true if a message is available
davidr99 0:ab4e012489ef 115 bool waitAvailableTimeout(uint16_t timeout);
davidr99 0:ab4e012489ef 116
davidr99 0:ab4e012489ef 117 /// Sets the TO header to be sent in all subsequent messages
davidr99 0:ab4e012489ef 118 /// \param[in] to The new TO header value
davidr99 0:ab4e012489ef 119 void setHeaderTo(uint8_t to);
davidr99 0:ab4e012489ef 120
davidr99 0:ab4e012489ef 121 /// Sets the FROM header to be sent in all subsequent messages
davidr99 0:ab4e012489ef 122 /// \param[in] from The new FROM header value
davidr99 0:ab4e012489ef 123 void setHeaderFrom(uint8_t from);
davidr99 0:ab4e012489ef 124
davidr99 0:ab4e012489ef 125 /// Sets the ID header to be sent in all subsequent messages
davidr99 0:ab4e012489ef 126 /// \param[in] id The new ID header value
davidr99 0:ab4e012489ef 127 void setHeaderId(uint8_t id);
davidr99 0:ab4e012489ef 128
davidr99 0:ab4e012489ef 129 /// Sets and clears bits in the FLAGS header to be sent in all subsequent messages
davidr99 0:ab4e012489ef 130 /// \param[in] set bitmask of bits to be set
davidr99 0:ab4e012489ef 131 /// \param[in] clear bitmask of flags to clear
davidr99 0:ab4e012489ef 132 void setHeaderFlags(uint8_t set, uint8_t clear = RH_FLAGS_NONE);
davidr99 0:ab4e012489ef 133
davidr99 0:ab4e012489ef 134 /// Returns the TO header of the last received message
davidr99 0:ab4e012489ef 135 /// \return The TO header of the most recently received message.
davidr99 0:ab4e012489ef 136 uint8_t headerTo();
davidr99 0:ab4e012489ef 137
davidr99 0:ab4e012489ef 138 /// Returns the FROM header of the last received message
davidr99 0:ab4e012489ef 139 /// \return The FROM header of the most recently received message.
davidr99 0:ab4e012489ef 140 uint8_t headerFrom();
davidr99 0:ab4e012489ef 141
davidr99 0:ab4e012489ef 142 /// Returns the ID header of the last received message
davidr99 0:ab4e012489ef 143 /// \return The ID header of the most recently received message.
davidr99 0:ab4e012489ef 144 uint8_t headerId();
davidr99 0:ab4e012489ef 145
davidr99 0:ab4e012489ef 146 /// Returns the FLAGS header of the last received message
davidr99 0:ab4e012489ef 147 /// \return The FLAGS header of the most recently received message.
davidr99 0:ab4e012489ef 148 uint8_t headerFlags();
davidr99 0:ab4e012489ef 149
davidr99 0:ab4e012489ef 150 /// Returns the address of this node.
davidr99 0:ab4e012489ef 151 /// \return The address of this node
davidr99 0:ab4e012489ef 152 uint8_t thisAddress();
davidr99 0:ab4e012489ef 153
davidr99 0:ab4e012489ef 154 protected:
davidr99 0:ab4e012489ef 155 /// The Driver we are to use
davidr99 0:ab4e012489ef 156 RHGenericDriver& _driver;
davidr99 0:ab4e012489ef 157
davidr99 0:ab4e012489ef 158 /// The address of this node
davidr99 0:ab4e012489ef 159 uint8_t _thisAddress;
davidr99 0:ab4e012489ef 160 };
davidr99 0:ab4e012489ef 161
davidr99 0:ab4e012489ef 162 #endif