Open Lighting Architecture: include/ola/rdm/DiscoveryAgent.h Source File

| Open Lighting Architecture 0.10.9

Loading...
Searching...
No Matches
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
28
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 <memory>
36#include <queue>
37#include <stack>
38#include <utility>
39
40namespace ola {
41namespace rdm {
42
53 class DiscoveryTargetInterface {
54 public:
60 typedef ola::BaseCallback1<void, bool> MuteDeviceCallback;
61
65 typedef ola::BaseCallback0<void> UnMuteDeviceCallback;
66
72 typedef ola::BaseCallback2<void, const uint8_t*, unsigned int>
73 BranchCallback;
74
75 virtual ~DiscoveryTargetInterface() {}
76
83 virtual void MuteDevice(const UID &target,
84 MuteDeviceCallback *mute_complete) = 0;
85
91 virtual void UnMuteAll(UnMuteDeviceCallback *unmute_complete) = 0;
92
102 virtual void Branch(const UID &lower,
103 const UID &upper,
104 BranchCallback *callback) = 0;
105};
106
107
135 class DiscoveryAgent {
136 public:
141 explicit DiscoveryAgent(DiscoveryTargetInterface *target);
142
146 ~DiscoveryAgent();
147
148 typedef ola::SingleUseCallback2<void, bool, const UIDSet&>
149 DiscoveryCompleteCallback;
150
156 void Abort();
157
162 void StartFullDiscovery(DiscoveryCompleteCallback *on_complete);
163
168 void StartIncrementalDiscovery(DiscoveryCompleteCallback *on_complete);
169
170 private:
174 struct UIDRange {
175 UIDRange(const UID &_lower, const UID &_upper, UIDRange *_parent)
176 : lower(_lower),
177 upper(_upper),
178 parent(_parent),
179 attempt(0),
180 failures(0),
181 uids_discovered(0),
182 branch_corrupt(false) {
183 }
184 UID lower;
185 UID upper;
186 UIDRange *parent; // the parent Range
187 unsigned int attempt; // the # of attempts for this branch
188 unsigned int failures;
189 unsigned int uids_discovered;
190 bool branch_corrupt; // true if this branch contains a bad device
191 };
192
193 typedef std::stack<UIDRange*> UIDRanges;
194
195 DiscoveryTargetInterface *m_target;
196 UIDSet m_uids;
197 // uids that are misbehaved in some way
198 UIDSet m_bad_uids;
199 DiscoveryCompleteCallback *m_on_complete;
200 // uids to mute during incremental discovery
201 std::queue<UID> m_uids_to_mute;
202 // Callbacks used by the DiscoveryTarget
203 std::auto_ptr<DiscoveryTargetInterface::UnMuteDeviceCallback>
204 m_unmute_callback;
205 std::auto_ptr<DiscoveryTargetInterface::MuteDeviceCallback>
206 m_incremental_mute_callback;
207 std::auto_ptr<DiscoveryTargetInterface::MuteDeviceCallback>
208 m_branch_mute_callback;
209 std::auto_ptr<DiscoveryTargetInterface::BranchCallback> m_branch_callback;
210
211 // The stack of UIDRanges
212 UIDRanges m_uid_ranges;
213 UID m_muting_uid; // the uid we're currently trying to mute
214 unsigned int m_unmute_count;
215 unsigned int m_mute_attempts;
216 bool m_tree_corrupt; // true if there was a problem with discovery
217
218 void InitDiscovery(DiscoveryCompleteCallback *on_complete,
219 bool incremental);
220
221 void UnMuteComplete();
222 void MaybeMuteNextDevice();
223 void IncrementalMuteComplete(bool status);
224 void SendDiscovery();
225
226 void BranchComplete(const uint8_t *data, unsigned int length);
227 void BranchMuteComplete(bool status);
228 void HandleCollision();
229 void FreeCurrentRange();
230
231 static const unsigned int PREAMBLE_SIZE = 8;
232 static const unsigned int EUID_SIZE = 12;
233 static const unsigned int CHECKSUM_SIZE = 4;
234
235 /*
236 * The maximum numbers of times we'll retry discovery if we get a
237 * collision, but after splitting the range in two no nodes can be found.
238 */
239 static const unsigned int MAX_EMPTY_BRANCH_ATTEMPTS = 5;
240 /*
241 * The maximum number of times we'll perform discovery on a branch when we
242 * get an inconsistent result (responder not muting, etc.)
243 */
244 static const unsigned int MAX_BRANCH_FAILURES = 5;
245
246 // The number of times we'll attempt to mute a UID
247 static const unsigned int MAX_MUTE_ATTEMPTS = 5;
248 // The number of times we'll send a broadcast unmute command
249 // This should be more than 1 to ensure that all devices are unmuted.
250 static const unsigned int BROADCAST_UNMUTE_REPEATS = 3;
251
252 static const uint8_t PREAMBLE = 0xfe;
253 static const uint8_t PREAMBLE_SEPARATOR = 0xaa;
254};
255} // namespace rdm
256} // namespace ola
257#endif // INCLUDE_OLA_RDM_DISCOVERYAGENT_H_
Callback.h
UID.h
A RDM unique identifier (UID).
UIDSet.h
A set of UIDs.
ola::BaseCallback0
The base class for all 0 argument callbacks.
Definition Callback.h:119
ola::BaseCallback1
The base class for all 1 argument callbacks.
Definition Callback.h:982
ola::BaseCallback2
The base class for all 2 argument callbacks.
Definition Callback.h:1885
ola::SingleUseCallback2
A 2 argument callback which deletes itself after it's run.
Definition Callback.h:1907
ola::rdm::DiscoveryAgent::StartFullDiscovery
void StartFullDiscovery(DiscoveryCompleteCallback *on_complete)
Initiate a full discovery operation.
Definition DiscoveryAgent.cpp:70
ola::rdm::DiscoveryAgent::Abort
void Abort()
Cancel any in-progress discovery operation. If a discovery operation is running, this will result in ...
Definition DiscoveryAgent.cpp:55
ola::rdm::DiscoveryAgent::StartIncrementalDiscovery
void StartIncrementalDiscovery(DiscoveryCompleteCallback *on_complete)
Initiate an incremental discovery operation.
Definition DiscoveryAgent.cpp:75
ola::rdm::DiscoveryAgent::DiscoveryAgent
DiscoveryAgent(DiscoveryTargetInterface *target)
Create a new DiscoveryAgent.
Definition DiscoveryAgent.cpp:34
ola::rdm::DiscoveryAgent::~DiscoveryAgent
~DiscoveryAgent()
Destructor.
Definition DiscoveryAgent.cpp:51
ola::rdm::DiscoveryTargetInterface
The interface used by the DiscoveryTarget to send RDM commands.
Definition DiscoveryAgent.h:53
ola::rdm::DiscoveryTargetInterface::MuteDeviceCallback
ola::BaseCallback1< void, bool > MuteDeviceCallback
The callback run when a mute command completes.
Definition DiscoveryAgent.h:60
ola::rdm::DiscoveryTargetInterface::BranchCallback
ola::BaseCallback2< void, const uint8_t *, unsigned int > BranchCallback
The callback run when a DUB command completes.
Definition DiscoveryAgent.h:73
ola::rdm::DiscoveryTargetInterface::UnMuteAll
virtual void UnMuteAll(UnMuteDeviceCallback *unmute_complete)=0
Unmute all devices.
ola::rdm::DiscoveryTargetInterface::UnMuteDeviceCallback
ola::BaseCallback0< void > UnMuteDeviceCallback
The callback run when an unmute command completes.
Definition DiscoveryAgent.h:65
ola::rdm::DiscoveryTargetInterface::MuteDevice
virtual void MuteDevice(const UID &target, MuteDeviceCallback *mute_complete)=0
Mute a device.
ola::rdm::DiscoveryTargetInterface::Branch
virtual void Branch(const UID &lower, const UID &upper, BranchCallback *callback)=0
Send a DUB command.
ola::rdm::UID
Represents a RDM UID.
Definition UID.h:57
ola::rdm::UIDSet
Represents a set of RDM UIDs.
Definition UIDSet.h:48
ola::rdm
PLASA E1.20 Remote Device Management.
Definition AckTimerResponder.cpp:38
ola
The namespace containing all OLA symbols.
Definition Credentials.cpp:44