Open Lighting Architecture  0.9.3
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
DiscoveryAgent.h
Go to the documentation of this file.
1 /*
2  * This library is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU Lesser General Public
4  * License as published by the Free Software Foundation; either
5  * version 2.1 of the License, or (at your option) any later version.
6  *
7  * This library is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10  * Lesser General Public License for more details.
11  *
12  * You should have received a copy of the GNU Lesser General Public
13  * License along with this library; if not, write to the Free Software
14  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
15  *
16  * DiscoveryAgent.h
17  * Implements the RDM Discovery algorithm.
18  * Copyright (C) 2011 Simon Newton
19  */
20 
29 #ifndef INCLUDE_OLA_RDM_DISCOVERYAGENT_H_
30 #define INCLUDE_OLA_RDM_DISCOVERYAGENT_H_
31 
32 #include <ola/Callback.h>
33 #include <ola/rdm/UID.h>
34 #include <ola/rdm/UIDSet.h>
35 #include <queue>
36 #include <stack>
37 #include <utility>
38 
39 
40 namespace ola {
41 namespace rdm {
42 
49  public:
50  // Argument is true if the device responded
53  // Arguments are a pointer to the data & length of the DUB response,
54  // excluding the RDM start code.
57 
58  virtual ~DiscoveryTargetInterface() {}
59 
60  // Mute a device
61  virtual void MuteDevice(const UID &target,
62  MuteDeviceCallback *mute_complete) = 0;
63  // Un Mute all devices
64  virtual void UnMuteAll(UnMuteDeviceCallback *unmute_complete) = 0;
65 
66  // Send a branch request
67  virtual void Branch(const UID &lower,
68  const UID &upper,
69  BranchCallback *callback) = 0;
70 };
71 
72 
77  public:
78  explicit DiscoveryAgent(DiscoveryTargetInterface *target);
80 
83 
84  void Abort();
87 
88  private:
92  struct UIDRange {
93  UIDRange(const UID &lower, const UID &upper, UIDRange *parent)
94  : lower(lower),
95  upper(upper),
96  parent(parent),
97  attempt(0),
98  failures(0),
99  uids_discovered(0),
100  branch_corrupt(false) {
101  }
102  UID lower;
103  UID upper;
104  UIDRange *parent; // the parent Range
105  unsigned int attempt; // the # of attempts for this branch
106  unsigned int failures;
107  unsigned int uids_discovered;
108  bool branch_corrupt; // true if this branch contains a bad device
109  };
110 
111  typedef std::stack<UIDRange*> UIDRanges;
112 
113  DiscoveryTargetInterface *m_target;
114  UIDSet m_uids;
115  // uids that are misbehaved in some way
116  UIDSet m_bad_uids;
117  DiscoveryCompleteCallback *m_on_complete;
118  // uids to mute during incremental discovery
119  std::queue<UID> m_uids_to_mute;
120  // Callbacks used by the DiscoveryTarget
122  DiscoveryTargetInterface::MuteDeviceCallback *m_incremental_mute_callback;
123  DiscoveryTargetInterface::MuteDeviceCallback *m_branch_mute_callback;
124  DiscoveryTargetInterface::BranchCallback *m_branch_callback;
125  // The stack of UIDRanges
126  UIDRanges m_uid_ranges;
127  UID m_muting_uid; // the uid we're currently trying to mute
128  unsigned int m_mute_attempts;
129  bool m_tree_corrupt; // true if there was a problem with discovery
130 
131  void InitDiscovery(DiscoveryCompleteCallback *on_complete,
132  bool incremental);
133 
134  void UnMuteComplete();
135  void MaybeMuteNextDevice();
136  void IncrementalMuteComplete(bool status);
137  void SendDiscovery();
138 
139  void BranchComplete(const uint8_t *data, unsigned int length);
140  void BranchMuteComplete(bool status);
141  void HandleCollision();
142  void FreeCurrentRange();
143 
144  static const unsigned int MAX_DUB_RESPONSE_SIZE = 24;
145  static const unsigned int MIN_DUB_RESPONSE_SIZE = 17;
146  /*
147  * The maximum numbers of times we'll retry discovery if we get a
148  * collision, but after splitting the range in two no nodes can be found.
149  */
150  static const unsigned int MAX_EMPTY_BRANCH_ATTEMPTS = 5;
151  /*
152  * The maximum number of times we'll perform discovery on a branch when we
153  * get an inconsistent result (responder not muting, etc.)
154  */
155  static const unsigned int MAX_BRANCH_FAILURES = 5;
156  // The number of times we'll attempt to mute a UID
157  static const unsigned int MAX_MUTE_ATTEMPTS = 5;
158 };
159 } // namespace rdm
160 } // namespace ola
161 #endif // INCLUDE_OLA_RDM_DISCOVERYAGENT_H_