HopeRF
HRFDatagram.h
1 // HRFDatagram.h
2 //
3 // Author: Mike McCauley (mikem@airspayce.com)
4 // Copyright (C) 2009 Mike McCauley
5 // $Id: HRFDatagram.h,v 1.1 2009/08/15 05:32:58 mikem Exp mikem $
6 
7 #ifndef HRFDatagram_h
8 #define HRFDatagram_h
9 
10 #include <HRFMessage.h>
11 
12 // Broadcast address
13 #define HRF_BROADCAST_ADDRESS 0xff
14 
15 // The maximum payload length
16 #define HRF_MAX_DATAGRAM_PAYLOAD HRF_MAX_PAYLOAD-2
17 
18 /////////////////////////////////////////////////////////////////////
19 /// \class HRFDatagram HRFDatagram.h <HRFDatagram.h>
20 /// \brief Class for addressed, unreliable messages
21 ///
22 /// Extends HRFMessage to define addressed, unreliable datagrams.
23 /// Every node has an 8 bit address (defaults to 0).
24 /// Datagrams have format LEN DEST SRC payload FCS-LO FCS-HI.
25 /// Addresses (DEST and SRC) are 8 bit integers with an address of HRF_BROADCAST_ADDRESS (0xff)
26 /// reserved for broadcast.
27 ///
28 /// Part of the Arduino HopeRF library for operating with HopeRF HM-TR transceivers
29 /// (see http://www.hoperf.com).
30 class HRFDatagram : public HRFMessage
31 {
32 protected:
33  /// The address of this node. Defaults to 0.
34  uint8_t _thisAddress;
35 
36 public:
37  /// \param[in] serial The instance of HardwareSerial to use for IO. Defaults to &Serial,
38  /// \param[in] thisAddress The address to assign to this node. Defaults to 0
39  HRFDatagram(HardwareSerial* serial = &Serial, uint8_t thisAddress = 0);
40 
41  /// Sets the address of this node. Defaults to 0. If all the nodes leave the address unset (ie 0),
42  /// HRFDatagram acts much the same as HRFMessage (with a bit more overhead).
43  /// In a conventional multinode system, all nodes will have a unique address (which you could store in EEPROM).
44  /// However, if you only have 2 nodes in the network,
45  /// you can leave the addresses of each set to the default of 0.
46  /// \param[in] thisAddress The address of this node
47  virtual void setThisAddress(uint8_t thisAddress);
48 
49  /// Sends a message to the node(s) with the given address
50  /// HRF_BROADCAST_ADDRESS is a valid address which will cause the message
51  /// to be accepted by all HRFDatagram nodes within range.
52  /// \param[in] address The address to send the message to.
53  /// \param[in] buf Pointer to the binary message to send
54  /// \param[in] len Number of octets to send
55  /// \return true if the message was transmitted.
56  /// \return false if the message is too long (>HRF_MAX_DATAGRAM_PAYLOAD).
57  virtual uint8_t sendto(uint8_t address, uint8_t* buf, uint8_t len);
58 
59  /// If there is a message available for this node, copy it to buf and return true
60  /// If the message was valid (ie good FCS), return true else return false.
61  /// The SRC address is placed in *from if present and not NULL.
62  /// The DEST address is placed in *to if present and not NULL.
63  /// If promiscuous is present and true, all messages will be returned, not just those addressed
64  /// to this node.
65  /// If a message is copied, *len is set to the length.
66  /// \param[in] buf Location to copy the received message
67  /// \param[in] len Available space in buf. Set to the actual number of octets copied.
68  /// \param[in] from If present and not NULL, the referenced uint8_t will be set to the SRC address
69  /// \param[in] to If present and not NULL, the referenced uint8_t will be set to the DEST address
70  /// \param[in] promiscuous If present and true, return all received messages
71  /// (not just those addressed to this node).
72  /// \return true if a valid (good FCS) message was copied to buf
73  virtual uint8_t recvfrom(uint8_t* buf, uint8_t* len, uint8_t* from = NULL, uint8_t* to = NULL, uint8_t promiscuous = 0);
74 
75  /// If there is a valid message available for this node, copy it to buf and return true
76  /// else return false. You can't recover the SRC or DEST address with this call, so you would only use it
77  /// if you do not intend to reply.
78  /// If a message is copied, *len is set to the length.
79  /// \param[in] buf Location to copy the received message
80  /// \param[in] len Available space in buf. Set to the actual number of octets copied.
81  /// \return true if a valid message was copied to buf
82  virtual uint8_t recv(uint8_t* buf, uint8_t* len);
83 
84 };
85 
86 #endif