DTrackSDK  v2.9.0
DTrackSDK.hpp
1 /* DTrackSDK in C++: DTrackSDK.hpp
2  *
3  * Functions to receive and process DTrack UDP packets (ASCII protocol), as
4  * well as to exchange DTrack2/DTRACK3 TCP command strings.
5  *
6  * Copyright (c) 2007-2024 Advanced Realtime Tracking GmbH & Co. KG
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions are met:
10  *
11  * 1. Redistributions of source code must retain the above copyright
12  * notice, this list of conditions and the following disclaimer.
13  * 2. Redistributions in binary form must reproduce the above copyright
14  * notice, this list of conditions and the following disclaimer in the
15  * documentation and/or other materials provided with the distribution.
16  * 3. Neither the name of copyright holder nor the names of its contributors
17  * may be used to endorse or promote products derived from this software
18  * without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
21  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
22  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30  *
31  * Version v2.9.0
32  *
33  * Purpose:
34  * - receives DTrack UDP packets (ASCII protocol) and converts them into easier to handle data
35  * - sends and receives DTrack2/DTRACK3 commands (TCP)
36  * - DTrack network protocol according to:
37  * 'DTrack2 User Manual, Technical Appendix' or 'DTRACK3 Programmer's Guide'
38  */
39 
59 #ifndef _ART_DTRACKSDK_HPP_
60 #define _ART_DTRACKSDK_HPP_
61 
62 #include "DTrackDataTypes.hpp"
63 #include "DTrackNet.hpp"
64 #include "DTrackParser.hpp"
65 
66 #include <string>
67 #include <vector>
68 
70 #define DTRACK_PROT_MAXLEN DTrackSDK::DTRACK2_PROT_MAXLEN
71 
77 class DTrackSDK : public DTrackParser
78 {
79 public:
80 
81  static const int DTRACK2_PROT_MAXLEN = 200;
82 
84  typedef enum {
89 
91  typedef enum {
92  ERR_NONE = 0,
96  } Errors;
97 
112  DTrackSDK( const std::string& connection );
113 
122  DTrackSDK(unsigned short data_port);
123 
138  DTrackSDK(const std::string& server_host, unsigned short data_port);
139 
147  DTrackSDK(const std::string& server_host, unsigned short server_port, unsigned short data_port);
148 
160  DTrackSDK(const std::string& server_host,
161  unsigned short server_port,
162  unsigned short data_port,
163  RemoteSystemType remote_type,
164  int data_bufsize = 0,
165  int data_timeout_us = 0,
166  int srv_timeout_us = 0
167  );
168 
172  ~DTrackSDK();
173 
174 
186  bool isValid();
187 
196  bool isDataInterfaceValid() const;
197 
205  bool isUDPValid() const { return isDataInterfaceValid(); }
206 
214  bool isLocalDataPortValid() const { return isDataInterfaceValid(); }
215 
221  unsigned short getDataPort() const;
222 
228  bool isCommandInterfaceValid() const;
229 
237  bool isTCPValid() const { return isCommandInterfaceValid(); }
238 
245 
252 
259  bool setDataTimeoutUS( int timeout );
260 
267  bool setCommandTimeoutUS( int timeout );
268 
277  bool setControllerTimeoutUS( int timeout ) { return setCommandTimeoutUS( timeout ); };
278 
285  bool setDataBufferSize( int bufSize );
286 
297  bool enableStatefulFirewallConnection( const std::string& senderHost, unsigned short senderPort = DTRACK2_PORT_UDPSENDER );
298 
299 
308  bool receive();
309 
318  bool processPacket( const std::string& data );
319 
325  std::string getBuf() const;
326 
327 
333  Errors getLastDataError() const;
334 
340  Errors getLastServerError() const;
341 
347  int getLastDTrackError() const;
348 
354  std::string getLastDTrackErrorDescription() const;
355 
356 
364  bool startMeasurement();
365 
371  bool stopMeasurement();
372 
373 
382  bool sendDTrack1Command( const std::string& command );
383 
392  bool sendCommand( const std::string& command ) { return sendDTrack1Command( command ); }
393 
408  int sendDTrack2Command(const std::string& command, std::string* answer = NULL);
409 
418  bool setParam(const std::string& category, const std::string& name, const std::string& value);
419 
426  bool setParam(const std::string& parameter);
427 
436  bool getParam(const std::string& category, const std::string& name, std::string& value);
437 
445  bool getParam(const std::string& parameter, std::string& value);
446 
447 
456  bool getMessage();
457 
463  unsigned int getMessageFrameNr() const;
464 
470  unsigned int getMessageErrorId() const;
471 
477  std::string getMessageOrigin() const;
478 
484  std::string getMessageStatus() const;
485 
491  std::string getMessageMsg() const;
492 
493 
507  bool tactileFinger( int handId, int fingerId, double strength );
508 
521  bool tactileHand( int handId, const std::vector< double >& strength );
522 
533  bool tactileHandOff( int handId, int numFinger );
534 
535 
547  bool flystickBeep( int flystickId, double durationMs, double frequencyHz );
548 
559  bool flystickVibration( int flystickId, int vibrationPattern );
560 
561 
562 private:
563 
564  static const unsigned short DTRACK2_PORT_COMMAND = 50105;
565  static const unsigned short DTRACK2_PORT_UDPSENDER = 50107;
566  static const unsigned short DTRACK2_PORT_FEEDBACK = 50110;
567 
568  static const int DEFAULT_TCP_TIMEOUT = 10000000;
569  static const int DEFAULT_UDP_TIMEOUT = 1000000;
570  static const int DEFAULT_UDP_BUFSIZE = 32768;
571 
578  void setLastDTrackError(int newError = 0, const std::string& newErrorString = "");
579 
588  void init( const std::string& server_host, unsigned short server_port, unsigned short data_port,
589  RemoteSystemType remote_type );
590 
598  bool sendStatefulFirewallPacket();
599 
606  bool sendFeedbackCommand( const std::string& command );
607 
608  RemoteSystemType rsType;
609  Errors lastDataError;
610  Errors lastServerError;
611 
612  int lastDTrackError;
613  std::string lastDTrackErrorString;
614 
615  DTrackNet::TCP* d_tcp;
616  int d_tcptimeout_us;
617 
618  DTrackNet::UDP* d_udp;
619  unsigned int d_remoteIp;
620  unsigned short d_remoteDT1Port;
621  int d_udptimeout_us;
622  unsigned int d_udpSenderIp;
623  unsigned short d_udpSenderPort; //<! Port number from which Controller is sending tracking data
624 
625  int d_udpbufsize;
626  char* d_udpbuf;
627 
628  std::string d_message_origin;
629  std::string d_message_status;
630  unsigned int d_message_framenr;
631  unsigned int d_message_errorid;
632  std::string d_message_msg;
633 };
634 
635 
636 #endif // _ART_DTRACKSDK_HPP_
637 
bool setDataBufferSize(int bufSize)
Set UDP buffer size for receiving tracking data.
Definition: DTrackSDK.cpp:399
Errors
Error codes.
Definition: DTrackSDK.hpp:91
std::string getBuf() const
Get content of the UDP buffer.
Definition: DTrackSDK.cpp:537
DTrack Parser class.
bool receive()
Receive and process one tracking data packet.
Definition: DTrackSDK.cpp:441
unsigned short getDataPort() const
Get UDP data port where tracking data is received.
Definition: DTrackSDK.cpp:321
bool isCommandInterfaceFullAccess()
Returns if TCP connection has full access for DTrack2/DTRACK3 commands.
Definition: DTrackSDK.cpp:341
bool setParam(const std::string &category, const std::string &name, const std::string &value)
Set DTrack2/DTRACK3 parameter.
Definition: DTrackSDK.cpp:807
bool setControllerTimeoutUS(int timeout)
Alias for setCommandTimeoutUS(). DEPRECATED.
Definition: DTrackSDK.hpp:277
std::string getMessageOrigin() const
Get origin of last DTrack2/DTRACK3 event message.
Definition: DTrackSDK.cpp:940
DTrackSDK(const std::string &connection)
Universal constructor. Can be used for any mode. Recommended for new applications.
Definition: DTrackSDK.cpp:60
bool enableStatefulFirewallConnection(const std::string &senderHost, unsigned short senderPort=DTRACK2_PORT_UDPSENDER)
Enable UDP connection through a stateful firewall.
Definition: DTrackSDK.cpp:425
bool setDataTimeoutUS(int timeout)
Set UDP timeout for receiving tracking data.
Definition: DTrackSDK.cpp:365
Handling TCP data.
Definition: DTrackNet.hpp:139
bool isTCPValid() const
Alias for isCommandInterfaceValid(). DEPRECATED.
Definition: DTrackSDK.hpp:237
std::string getLastDTrackErrorDescription() const
Get last DTrack2/DTRACK3 command error description.
Definition: DTrackSDK.cpp:576
unsigned int getMessageErrorId() const
Get error id of last DTrack2/DTRACK3 event message.
Definition: DTrackSDK.cpp:931
RemoteSystemType getRemoteSystemType() const
Get current remote system type (e.g. DTrack1, DTrack2/DTRACK3).
Definition: DTrackSDK.cpp:356
bool tactileFinger(int handId, int fingerId, double strength)
Send tactile FINGERTRACKING command to set feedback on a specific finger of a specific hand...
Definition: DTrackSDK.cpp:967
bool isUDPValid() const
Alias for isDataInterfaceValid(). DEPRECATED.
Definition: DTrackSDK.hpp:205
bool getParam(const std::string &category, const std::string &name, std::string &value)
Get DTrack2/DTRACK3 parameter.
Definition: DTrackSDK.cpp:826
unsigned int getMessageFrameNr() const
Get frame counter of last DTrack2/DTRACK3 event message.
Definition: DTrackSDK.cpp:922
DTrack SDK main class derived from DTrackParser.
Definition: DTrackSDK.hpp:77
std::string getMessageStatus() const
Get status of last DTrack2/DTRACK3 event message.
Definition: DTrackSDK.cpp:949
bool processPacket(const std::string &data)
Process one tracking packet manually.
Definition: DTrackSDK.cpp:493
static const int DTRACK2_PROT_MAXLEN
max. length of &#39;dtrack2&#39; command
Definition: DTrackSDK.hpp:81
Errors getLastServerError() const
Get last error at exchanging commands with Controller (command transmission).
Definition: DTrackSDK.cpp:558
bool isCommandInterfaceValid() const
Returns if TCP connection for DTrack2/DTRACK3 commands is active.
Definition: DTrackSDK.cpp:330
bool flystickVibration(int flystickId, int vibrationPattern)
Send Flystick feedback command to start a vibration pattern on a specific Flystick.
Definition: DTrackSDK.cpp:1040
bool sendDTrack1Command(const std::string &command)
Send DTrack1 command via UDP.
Definition: DTrackSDK.cpp:633
std::string getMessageMsg() const
Get message text of last DTrack2/DTRACK3 event message.
Definition: DTrackSDK.cpp:958
DTrack2/DTRACK3 system.
Definition: DTrackSDK.hpp:87
bool flystickBeep(int flystickId, double durationMs, double frequencyHz)
Send Flystick feedback command to start a beep on a specific Flystick.
Definition: DTrackSDK.cpp:1025
bool sendCommand(const std::string &command)
Alias for sendDTrack1Command(). DEPRECATED.
Definition: DTrackSDK.hpp:392
Timeout occured.
Definition: DTrackSDK.hpp:93
RemoteSystemType
Compatibility modes for older DTrack systems.
Definition: DTrackSDK.hpp:84
Error while parsing command.
Definition: DTrackSDK.hpp:95
bool isDataInterfaceValid() const
Returns if UDP socket is open to receive tracking data on local machine.
Definition: DTrackSDK.cpp:310
bool getMessage()
Get DTrack2/DTRACK3 event message from the Controller.
Definition: DTrackSDK.cpp:864
Errors getLastDataError() const
Get last error at receiving tracking data (data transmission).
Definition: DTrackSDK.cpp:549
bool tactileHandOff(int handId, int numFinger)
Send tactile FINGERTRACKING command to turn off tactile feedback on all fingers of a specific hand...
Definition: DTrackSDK.cpp:1012
DTrack1 system.
Definition: DTrackSDK.hpp:86
bool stopMeasurement()
Stop measurement.
Definition: DTrackSDK.cpp:615
bool startMeasurement()
Start measurement.
Definition: DTrackSDK.cpp:595
bool isLocalDataPortValid() const
Alias for isDataInterfaceValid(). DEPRECATED.
Definition: DTrackSDK.hpp:214
Handling UDP data.
Definition: DTrackNet.hpp:64
int getLastDTrackError() const
Get last DTrack2/DTRACK3 command error code.
Definition: DTrackSDK.cpp:567
~DTrackSDK()
Destructor.
Definition: DTrackSDK.cpp:279
bool setCommandTimeoutUS(int timeout)
Set TCP timeout for exchanging commands with Controller.
Definition: DTrackSDK.cpp:382
Network error.
Definition: DTrackSDK.hpp:94
int sendDTrack2Command(const std::string &command, std::string *answer=NULL)
Send DTrack2/DTRACK3 command to DTrack and receive answer (TCP command interface).
Definition: DTrackSDK.cpp:685
bool isValid()
Returns if constructor was successful due to the wanted mode.
Definition: DTrackSDK.cpp:294
bool tactileHand(int handId, const std::vector< double > &strength)
Send tactile FINGERTRACKING command to set tactile feedback on all fingers of a specific hand...
Definition: DTrackSDK.cpp:987