forked from PlusToolkit/ndicapi
-
Notifications
You must be signed in to change notification settings - Fork 0
/
ndicapi.h
2220 lines (1769 loc) · 81.6 KB
/
ndicapi.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*=======================================================================
Copyright (c) 2000-2005 Atamai, Inc.
Use, modification and redistribution of the software, in source or
binary forms, are permitted provided that the following terms and
conditions are met:
1) Redistribution of the source code, in verbatim or modified
form, must retain the above copyright notice, this license,
the following disclaimer, and any notices that refer to this
license and/or the following disclaimer.
2) Redistribution in binary form must include the above copyright
notice, a copy of this license and the following disclaimer
in the documentation or with other materials provided with the
distribution.
3) Modified copies of the source code must be clearly marked as such,
and must not be misrepresented as verbatim copies of the source code.
THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS"
WITHOUT EXPRESSED OR IMPLIED WARRANTY INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. IN NO EVENT SHALL ANY COPYRIGHT HOLDER OR OTHER PARTY WHO MAY
MODIFY AND/OR REDISTRIBUTE THE SOFTWARE UNDER THE TERMS OF THIS LICENSE
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, LOSS OF DATA OR DATA BECOMING INACCURATE
OR LOSS OF PROFIT OR BUSINESS INTERRUPTION) ARISING IN ANY WAY OUT OF
THE USE OR INABILITY TO USE THE SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
=======================================================================*/
/*! \file ndicapi.h
This file contains a complete C interface to the Northern Digital
Combined API.
*/
#ifndef NDICAPI_H
#define NDICAPI_H
#include "ndicapiExport.h"
#include "ndicapi_serial.h"
#include "ndicapi_socket.h"
#include "ndicapi_thread.h"
#include <stdarg.h>
#include <limits.h>
#define NDICAPI_MAJOR_VERSION 1
#define NDICAPI_MINOR_VERSION 7
// Max tools is 12 active plus 9 passive, so 24 is a safe number
// (note that we are only counting the number of handles that can
// be simultaneously occupied)
#define NDI_MAX_HANDLES 24
//----------------------------------------------------------------------------
// Structure for holding ndicapi data.
struct ndicapi
{
// low-level communication information
NDIFileHandle SerialDevice; // file handle for ndicapi
char* SerialDeviceName; // device name for ndicapi
NDISocketHandle Socket; // socket handle
char* Hostname; // socket hostname
int Port; // socket port
int SocketErrorCode; // error code (zero if no error)
char* Command; // text sent to the ndicapi
char* Reply; // reply from the ndicapi
// this is set to true during tracking mode
bool IsTracking;
// low-level threading information
bool IsThreadedMode; // flag for threading mode
NDIThread Thread; // the thread handle
NDIMutex ThreadMutex; // for blocking the thread
NDIMutex ThreadBufferMutex; // lock the reply buffer
NDIEvent ThreadBufferEvent; // for when buffer is updated
char* ThreadCommand; // last command sent from thread
char* ThreadReply; // reply from the ndicapi
char* ThreadBuffer; // buffer for previous reply
bool IsThreadedCommandBinary; // cache whether we're sending BX (true) or TX/GX (false)
int ThreadErrorCode; // error code to go with buffer
// command reply -- this is the return value from plCommand()
char* ReplyNoCRC; // reply without CRC and <CR>
// error handling information
int ErrorCode; // error code (zero if no error)
// Error callback
void (*ErrorCallback)(int code, char* description, void* data);
void* ErrorCallbackData; // user data for callback
// GX command reply data
char GxTransforms[3][52]; // 3 active tool transforms
char GxStatus[8]; // tool and system status
char GxInformation[3][12]; // extra transform information
char GxSingleStray[3][24]; // one stray marker per tool
char GxFrame[3][8]; // frame number for each tool
char GxPassiveTransforms[9][52]; // 9 passive tool transforms
char GxPassiveStatus[24]; // tool and system status
char GxPassiveInformation[9][12]; // extra transform information
char GxPassiveFrame[9][8]; // frame number for each tool
char GxPassiveStray[424]; // all passive stray markers
// PSTAT command reply data
char PstatBasic[3][32]; // basic pstat info
char PstatTesting[3][8]; // testing results
char PstatPartNumber[3][20]; // part number
char PstatAccessories[3][2]; // accessory information
char PstatMarkerType[3][2]; // marker information
char PstatPassiveBasic[9][32]; // basic passive pstat info
char PstatPassiveTesting[9][8]; // meaningless info
char PstatPassivePartNumber[9][20]; // virtual srom part number
char PstatPassiveAccessories[9][2]; // virtual srom accessories
char PstatPassiveMarkerType[9][2]; // meaningless for passive
// SSTAT command reply data
char SstatControl[2]; // control processor status
char SstatSensor[2]; // sensor processors status
char SstatTiu[2]; // tiu processor status
// IRCHK command reply data
int IrchkDetected; // irchk detected infrared
char IrchkSources[128]; // coordinates of sources
// PHRQ command reply data
char PhrqReply[2];
// PHSR command reply data
char PhsrReply[1284];
// PHINF command reply data
int PhinfUnoccupied;
char PhinfBasic[34];
char PhinfTesting[8];
char PhinfPartNumber[20];
char PhinfAccessories[2];
char PhinfMarkerType[2];
char PhinfPortLocation[14];
char PhinfGpioStatus[2];
// TX command reply data
int TxHandleCount;
unsigned char TxHandles[NDI_MAX_HANDLES];
char TxTransforms[NDI_MAX_HANDLES][52];
char TxStatus[NDI_MAX_HANDLES][8];
char TxFrame[NDI_MAX_HANDLES][8];
char TxInformation[NDI_MAX_HANDLES][12];
char TxSingleStray[NDI_MAX_HANDLES][24];
char TxSystemStatus[4];
int TxPassiveStrayCount;
char TxPassiveStrayOov[14];
char TxPassiveStray[1052];
// BX command reply data
unsigned short BxReplyLength;
unsigned char BxHandleCount;
char BxHandles[NDI_MAX_HANDLES];
char BxHandlesStatus[NDI_MAX_HANDLES];
unsigned int BxFrameNumber[NDI_MAX_HANDLES];
float BxTransforms[NDI_MAX_HANDLES][8];
int BxPortStatus[NDI_MAX_HANDLES];
char BxToolMarkerInformation[NDI_MAX_HANDLES][11];
char BxActiveSingleStrayMarkerStatus[NDI_MAX_HANDLES];
float BxActiveSingleStrayMarkerPosition[NDI_MAX_HANDLES][3];
char Bx3DMarkerCount[NDI_MAX_HANDLES];
char Bx3DMarkerOutOfVolume[NDI_MAX_HANDLES][3]; // 3 bytes holds 1 bit entries for up to 24 markers (but 20 is max)
float Bx3DMarkerPosition[NDI_MAX_HANDLES][20][3]; // a tool can have up to 20 markers
int BxPassiveStrayCount;
char BxPassiveStrayOutOfVolume[30]; // 30 bytes holds 1 bit entries for up to 240 markers
float BxPassiveStrayPosition[240][3]; // hold up to 240 stray markers
int BxSystemStatus;
};
typedef struct ndicapi ndicapi;
/*=====================================================================*/
/*! \defgroup NDIMethods Core Interface Methods
These are the primary set of methods for communicating with
tracking devices from NDI that follow the NDI Combined Application
Programmers' Interface.
*/
#ifdef __cplusplus
extern "C" {
#endif
/*! \ingroup NDIMethods
This function will return the name of the \em i th serial port device,
i.e. \em i = 0 gives "COM1:" on Windows and "/dev/ttyS0" on linux.
\param i integer between 0 and 3
\return the name of a serial port device or 0
If \em i is too large, the return value is zero.
*/
ndicapiExport const char* ndiSerialDeviceName(int i);
/*! \ingroup NDIMethods
Probe for an NDI device on the specified serial port device.
This will perform the following steps:
-# save the status of the device (baud rate etc)
-# open the device at 9600 baud, 8 data bits, no parity, 1 stop bit
-# send an "INIT:" command and check for the expected reply
-# if the "INIT:" failed, send a serial break and re-try the "INIT:"
-# if the "INIT:" succeeds, send "VER:0" and check for response.
-# restore the device to its previous state and close the device.
\param device name of a valid serial port device
\param checkDSR whether or not to perform a DSR check
\return one of:
- NDI_OKAY - probe was successful
- NDI_OPEN_ERROR - couldn't open the device
- NDI_BAD_COMM - device file is probably not a serial port
- NDI_WRITE_ERROR - I/O error while writing to the device
- NDI_READ_ERROR - I/O error while reading from device
- NDI_TIMEOUT - timeout while waiting for data
- NDI_PROBE_FAIL - the device found was not an NDI device
*/
ndicapiExport int ndiSerialProbe(const char* device, bool checkDSR);
/*! \ingroup NDIMethods
Open communication with the NDI device on the specified
serial port device. This also sets the serial port parameters to
(9600 baud, 8N1, no handshaking).
\param device name of a valid serial port device
\return 1 if an NDI device was found on the specified port, 0 otherwise
*/
ndicapiExport ndicapi* ndiOpenSerial(const char* device);
/*! \ingroup NDIMethods
Open communication with the NDI device on the specified
network host and port.
\param hostname URL of the NDI device
\param port Port of the NDI device
\return 1 if an NDI device was found at the specified address, 0 otherwise
*/
ndicapiExport ndicapi* ndiOpenNetwork(const char* hostname, int port);
/*! \ingroup NDIMethods
Close communication with the NDI device. You should send
a "COMM:00000" command before you close communication so that you
can resume communication on a subsequent call to ndiOpen() without
having to reset the NDI device.
*/
ndicapiExport void ndiCloseSerial(ndicapi* pol);
/*! \ingroup NDIMethods
Close communication with the NDI device.
*/
ndicapiExport void ndiCloseNetwork(ndicapi* pol);
/*! \ingroup NDIMethods
Set up multithreading to increase efficiency.
\param pol valid NDI device handle
\param mode true to turn on threading, false to turn off threading
It can take milliseconds or even tens of milliseconds for the tracking
system to return the transform data after a TX or GX command. During
this time, the application normally sits idle.
One way to avoid this idle time is to spawn a separate thread to send
the GX/TX/BX commands to the device and wait for the replies.
This allows the main application thread to continue to execute while
the other thread is waiting for a reply from the device.
When the thread mode is set, every time the application sends a GX,
TX or BX command to the device during tracking mode the
spawned thread will automatically begin resending the GX/TX/BX
command as fast as possible.
Then when the application sends the next GX/TX/BX command, the
thread will simply send the application the most recent reply
instead of forcing the application to wait through a full command/reply
cycle.
If the application changes the reply mode for the GX, TX or BX command,
then the thread will begin sending commands with the new reply format.
*/
ndicapiExport void ndiSetThreadMode(ndicapi* pol, bool mode);
/*! \ingroup NDIMethods
Send a command to the device using a printf-style format string.
\param pol valid NDI device handle
\param format a printf-style format string
\param ... format arguments as per the format string
\return the text reply from the device with the
CRC chopped off
The standard format of an NDI API command is, for example, "INIT:" or
"PENA:AD". A CRC value and a carriage return will be appended to the
command before it is sent to the device.
This function will automatically recognize certain commands and behave
accordingly:
- NULL - A serial break will be sent to the device.
- "COMM:" - After the COMM is sent, the host computer serial port is
adjusted to match the device.
- "INIT:" - After the INIT is sent, communication will be paused
for 100ms.
- "PHSR:" - The information returned by the PHSR command is stored and can
be retrieved though the ndiGetPHSR() functions.
- "PHINF:" - The information returned by the PHINF command is stored and can
be retrieved though the ndiGetPHINF() functions.
- "TX:" - The information returned by the GX command is stored and can
be retrieved though the ndiGetTX() functions.
- "GX:" - The information returned by the GX command is stored and can
be retrieved though the ndiGetGX() functions.
- "PSTAT:" - The information returned by the PSTAT command is stored and
can be retrieved through one of the ndiGetPSTAT() functions.
- "SSTAT:" - The information returned by the SSTAT command is stored and
can be retrieved through one of the ndiGetSSTAT() functions.
- "IRCHK:" - The information returned by the IRCHK command is stored and
can be retrieved through the ndiGetIRCHK() functions.
<p>The ndiGetError() function can be used to check whether an error
occured or, alternatively, ndiSetErrorCallback() can be used to set
a function that will be called whenever an error occurs.
For convenience, there is a set of macros for sending commands to the
devices. These are listed in \ref NDIMacros.
*/
ndicapiExport char* ndiCommand(ndicapi* pol, const char* format, ...);
/*! \ingroup NDIMethods
This function is identical in behaviour to ndiCommand(), except that
it accepts a va_list instead of an argument list. The use of va_list
is described in the standard C header file "stdarg.h".
*/
ndicapiExport char* ndiCommandVA(ndicapi* pol, const char* format, va_list ap);
/*! \ingroup NDIMethods
Error callback type for use with ndiSetErrorCallback().
*/
typedef void (*NDIErrorCallback)(int errnum, char* description, void* userdata);
/*! \ingroup NDIMethods
Set a function that will be called each time an error occurs.
\param pol valid NDI device handle
\param callback a callback with the following signature:\n
void callback(int errnum, char *error_description, void *userdata)
\param userdata data to send to the callback each time it is called
The callback can be set to NULL to erase a previous callback.
*/
ndicapiExport void ndiSetErrorCallback(ndicapi* pol, NDIErrorCallback callback,
void* userdata);
/*! \ingroup NDIMethods
Log current state of NDICAPI to string
\param outInformation A LF delimited string describing the state of each variable in the system in the format "<variableName>=<variableValue><LF><variableName>=..."
*/
ndicapiExport void ndiLogState(ndicapi* pol, char outInformation[USHRT_MAX]);
/*! \ingroup NDIMethods
Set the socket timeout
\param timeoutMsec the timeout in milliseconds
*/
ndicapiExport void ndiTimeoutSocket(ndicapi* pol, int timeoutMsec);
/*=====================================================================*/
/*! \defgroup NDIMacros Command Macros
These are a set of macros that send commands to the device via
ndiCommand().
The ndiGetError() function can be used to determine whether an error
occurred.
The return value is a terminated string containing the reply from the
device with the CRC and final carriage return chopped off.
*/
/*\{*/
/*!
Get the 3D position and an error value for a single marker on a
tool. The mode should be set to 1 or 3. This command is only
available in diagnostic mode.
\param ph valid port handle in the range 0x01 to 0xFF
\param mode see NDI documentation
The IRED command should be used to set up a marker firing signature
before this command is called.
*/
#define ndi3D(p,ph,mode) ndiCommand((p),"3D:%02X%d",(ph),(mode))
/*!
Cause the device to beep.
\param n the number of times to beep, an integer between 1 and 9
A reply of "0" means that the device is already beeping
and cannot service this beep request.
This command can be used in tracking mode.
*/
#define ndiBEEP(p,n) ndiCommand((p),"BEEP:%i",(n))
/*!
Change the device communication parameters. The host parameters
will automatically be adjusted to match. If the specified baud rate is
not supported by the serial port, then the error code will be set to
NDI_BAD_COMM and the device will have to be reset before
communication can continue. Most modern UNIX systems accept all baud
rates except 14400, and Windows systems support all baud rates.
\param baud one of NDI_9600, NDI_14400, NDI_19200, NDI_38400, NDI_57600,
NDI_115200
\param dps should usually be NDI_8N1, the most common mode
\param h one of NDI_HANDSHAKE or NDI_NOHANDSHAKE
*/
#define ndiCOMM(p,baud,dps,h) ndiCommand((p),"COMM:%d%03d%d",(baud),(dps),(h))
/*!
Put the device into diagnostic mode. This must be done prior
to executing the IRCHK() command. Diagnostic mode is only useful on
the POLARIS
*/
#define ndiDSTART(p) ndiCommand((p),"DSTART:")
/*!
Take the device out of diagnostic mode.
*/
#define ndiDSTOP(p) ndiCommand((p),"DSTOP:")
/*!
Request tracking information from the system. This command is
only available in tracking mode. Please note that this command has
been deprecated in favor of the TX command.
\param mode a reply mode containing the following bits:
- NDI_XFORMS_AND_STATUS 0x0001 - transforms and status
- NDI_ADDITIONAL_INFO 0x0002 - additional tool transform info
- NDI_SINGLE_STRAY 0x0004 - stray active marker reporting
- NDI_FRAME_NUMBER 0x0008 - frame number for each tool
- NDI_PASSIVE 0x8000 - include information for ports 'A', 'B', 'C'
- NDI_PASSIVE_EXTRA 0x2000 - with NDI_PASSIVE, ports 'A' to 'I'
- NDI_PASSIVE_STRAY 0x1000 - stray passive marker reporting
<p>The GX command with the appropriate reply mode is used to update the
data that is returned by the following functions:
- int \ref ndiGetGXTransform(ndicapi *pol, int port, double transform[8])
- int \ref ndiGetGXPortStatus(ndicapi *pol, int port)
- int \ref ndiGetGXSystemStatus(ndicapi *pol)
- int \ref ndiGetGXToolInfo(ndicapi *pol, int port)
- int \ref ndiGetGXMarkerInfo(ndicapi *pol, int port, int marker)
- int \ref ndiGetGXSingleStray(ndicapi *pol, int port, double coord[3])
- unsigned long \ref ndiGetGXFrame(ndicapi *pol, int port)
- int \ref ndiGetGXNumberOfPassiveStrays(ndicapi *pol)
- int \ref ndiGetGXPassiveStray(ndicapi *pol, int i, double coord[3])
*/
#define ndiGX(p,mode) ndiCommand((p),"GX:%04X",(mode))
/*!
Initialize the device. The device must be
initialized before any other commands are sent.
*/
#define ndiINIT(p) ndiCommand((p),"INIT:")
/*!
Set the POLARIS infrared firing rate to 20 Hz = 0, 30 Hz = 1, 20 Hz = 2
*/
#define ndiIRATE(p,rate) ndiCommand((p),"IRATE:%d",(rate))
/*!
Check for sources of environmental infrared. This command is only
valid in diagnostic mode after an IRINIT command.
\param mode reply mode bits:
- NDI_DETECTED 0x0001 - return '1' if IR detected, else '0'
- NDI_SOURCES 0x0002 - locations of up to 20 sources per camera
<p>The IRCHK command is used to update the information returned by the
ndiGetIRCHKDetected() and ndiGetIRCHKSourceXY() functions.
*/
#define ndiIRCHK(p,mode) ndiCommand((p),"IRCHK:%04X",(mode))
/*!
Set the infrared firing signature for the specified port. This
command is only available in diagnostic mode.
\param ph valid port handle in the range 0x01 to 0xFF
\param sig a 32-bit integer whose bits specify what IREDS to fire
*/
#define ndiIRED(p,ph,sig) ndiCommand((p),"IRED:%02X%08X",(ph),(sig))
/*!
Initialize the diagnostic environmental infrared checking system.
This command must be called prior to using the IRCHK command.
*/
#define ndiIRINIT(p) ndiCommand((p),"IRINIT:")
/*!
Set a tool LED to a particular state.
\param ph valid port handle in the range 0x01 to 0xFF
\param led an integer between 1 and 3
\param state desired state: NDI_BLANK 'B', NDI_FLASH 'F' or NDI_SOLID 'S'
This command can be used in tracking mode.
*/
#define ndiLED(p,ph,led,s) ndiCommand((p),"LED:%02X%d%c",(ph),(led),(s))
/*!
Disable transform reporting on the specified port handle.
\param ph valid port handle in the range 0x01 to 0xFF
*/
#define ndiPDIS(p,ph) ndiCommand((p),"PDIS:%02X",(ph))
/*!
Enable transform reporting on the specified port handle.
\param ph valid port handle in the range 0x01 to 0xFF
\param mode one of NDI_STATIC 'S', NDI_DYNAMIC 'D' or NDI_BUTTON_BOX 'B'
*/
#define ndiPENA(p,ph,mode) ndiCommand((p),"PENA:%02X%c",(ph),(mode))
/*!
Specify a POLARIS tool faces to use for tracking
\param ph valid port handle in the range 0x01 to 0xFF
\param tf tool face mask in the range 0x01 to 0xFF
*/
#define ndiPFSEL(p,ph,tf) ndiCommand((p),"PFSEL:%02X%02X",(ph),(tf))
/*!
Free the specified port handle.
\param ph valid port handle in the range 0x01 to 0xFF
*/
#define ndiPHF(p,ph) ndiCommand((p),"PHF:%02X",(ph))
/*!
Ask the device for information about a tool handle.
\param format a reply format mode composed of the following bits:
- NDI_BASIC 0x0001 - get port status and basic tool information
- NDI_TESTING 0x0002 - get current test for active tools
- NDI_PART_NUMBER 0x0004 - get a 20 character part number
- NDI_ACCESSORIES 0x0008 - get a summary of the tool accessories
- NDI_MARKER_TYPE 0x0010 - get the tool marker type
- NDI_PORT_LOCATION 0x0020 - get the physical port location
- NDI_GPIO_STATUS 0x0040 - get AURORA GPIO status
<p>The use of the PHINF command with the appropriate reply format updates
the information returned by the following commands:
- int \ref ndiGetPHINFPortStatus(ndicapi *pol)
- int \ref ndiGetPHINFToolInfo(ndicapi *pol, char information[30])
- unsigned long \ref ndiGetPHINFCurrentTest(ndicapi *pol)
- int \ref ndiGetPHINFAccessories(ndicapi *pol)
- int \ref ndiGetPHINFMarkerType(ndicapi *pol)
<p>This command is not available during tracking mode.
*/
#define ndiPHINF(p,ph,format) ndiCommand((p),"PHINF:%02X%04X",(ph),(format))
/*!
Requeset a port handle given specific tool criteria.
\param num 8-digit device number or wildcard "********"
\param sys system type TIU "0" or AURORA SCU "1" or wildcard "*"
\param tool wired "0" or wireless "1" or wildcard "*"
\param port wired "01" to "10", wireless "0A" to "0I" or wildcard "**"
\param chan AURORA tool channel "00" or "01" or wildcard "**"
<p>The use of the PHRQ command updates the information returned by the
following commands:
- int \ref ndiGetPHRQHandle(ndicapi *pol)
*/
#define ndiPHRQ(p,num,sys,tool,port,chan) ndiCommand((p),"PHRQ:%-8.8s%1.1s%1.1s%2.2s%2.2s",(num),(sys),(tool),(port),(chan))
/*!
List the port handles.
\param mode the reply mode:
- NDI_ALL_HANDLES 0x00 - return all handles
- NDI_STALE_HANDLES 0x01 - only handles waiting to be freed
- NDI_UNINITIALIZED_HANDLES 0x02 - handles needing initialization
- NDI_UNENABLED_HANDLES 0x03 - handles needing enabling
- NDI_ENABLED_HANDLES 0x04 - handles that are enabled
<p>The use of the PHSR command with the appropriate reply format updates
the information returned by the following commands:
- int \ref ndiGetPHSRNumberOfHandles(ndicapi *pol)
- int \ref ndiGetPHSRHandle(ndicapi *pol, int i)
- int \ref ndiGetPHSRInformation(ndicapi *pol, int i)
<p>This command is not available during tracking mode.
*/
#define ndiPHSR(p,mode) ndiCommand((p),"PHSR:%02X",(mode))
/*!
Initialize the tool on the specified port handle.
\param ph valid port handle in the range 0x01 to 0xFF
*/
#define ndiPINIT(p,ph) ndiCommand((p),"PINIT:%02X",(ph))
/*! Read the tool SROM. Use ndiHexDecode() to convert reply to binary. */
#define ndiPPRD(p,ph,addr) ndiCommand((p),"PPRD:%02X%04X",(ph),(addr))
/*! Write the tool SROM. Use ndiHexEncode() to convert data to a hex string. */
#define ndiPPWR(p,ph,a,x) ndiCommand((p),"PPWR:%02X%04X%.128s",(ph),(a),(x))
/*! Select an SROM target by ID. */
#define ndiPSEL(p,ph,id) ndiCommand((p),"PSEL:%02X%s",(ph),(id))
/*!
Set the three GPIO wire states for an AURORA tool.
The states available are 'N' (no change), 'S' (solid on),
'P' (pulse) and 'O' (off).
\param ph valid port handle in the range 0x01 to 0xFF
\param a GPIO 1 state
\param b GPIO 2 state
\param c GPIO 3 state
*/
#define ndiPSOUT(p,ph,a,b,c) ndiCommand((p),"PSOUT:%02X%c%c%c",(ph),(a),(b),(c))
/*! Search for available SROM targets. */
#define ndiPSRCH(p,ph) ndiCommand((p),"PSRCH:%02X",(ph))
/*!
Ask for information about the tool ports. This command has been
deprecated in favor of the PHINF command.
\param format a reply format mode composed of the following bits:
- NDI_BASIC 0x0001 - get port status and basic tool information
- NDI_TESTING 0x0002 - get current test for active tools
- NDI_PART_NUMBER 0x0004 - get a 20 character part number
- NDI_ACCESSORIES 0x0008 - get a summary of the tool accessories
- NDI_MARKER_TYPE 0x0010 - get the tool marker type
- NDI_PASSIVE 0x8000 - include information for ports 'A', 'B', 'C'
- NDI_PASSIVE_EXTRA 0x2000 - with NDI_PASSIVE, ports 'A' to 'I'
<p>The use of the PSTAT command with the appropriate reply format updates
the information returned by the following commands:
- int \ref ndiGetPSTATPortStatus(ndicapi *pol, int port)
- int \ref ndiGetPSTATToolInfo(ndicapi *pol, int port,
char information[30])
- unsigned long \ref ndiGetPSTATCurrentTest(ndicapi *pol, int port)
- int \ref ndiGetPSTATAccessories(ndicapi *pol, int port)
- int \ref ndiGetPSTATMarkerType(ndicapi *pol, int port)
<p>This command is not available during tracking mode.
*/
#define ndiPSTAT(p,format) ndiCommand((p),"PSTAT:%04X",(format))
/*! Read the user part of the tool SROM. Use ndiHexDecode() convert reply. */
#define ndiPURD(p,ph,addr) ndiCommand((p),"PURD:%02X%04X",(ph),(addr))
/*! Write the user part of the tool SROM. Use ndiHexEncode() to convert data.*/
#define ndiPUWR(p,ph,a,x) ndiCommand((p),"PPWR:%02X%04X%.128s",(ph),(a),(x))
/*!
Clear the virtual SROM for the specified port. For a passive tool,
this is equivalent to unplugging the tool. This command has been
deprecated in favor of PHF.
\param port one of '1', '2', '3' or 'A' to 'I'
*/
#define ndiPVCLR(p,port) ndiCommand((p),"PVCLR:%c",(port))
/*!
Set the virtual TOOL IN PORT and non-POLARIS tool signals for this port.
This command has been deprecated in favor of PHRQ.
\param port one of '1', '2', '3' or 'A' to 'I'
\param tip one of 0 (no tool in port) or 1 (tool in port)
\param type one of 0 (non-POLARIS tool) or 1 (POLARIS tool)
*/
#define ndiPVTIP(p,port,tip,np) ndiCommand((p),"PVTIP:%c%d%d",(port),(tip),(np))
/*!
Write to a virtual SROM address on the specified port handle.
The ndiPVWRFromFile() function provides a more convenient means
of uploading tool descriptions.
\param ph valid port handle in the range 0x01 to 0xFF
\param a an address between 0x0000 and 0x07C0
\param x 64-byte data array encoded as a 128-character hexidecimal string
The ndiHexEncode() function can be used to encode the data into
hexidecimal.
*/
#define ndiPVWR(p,ph,a,x) ndiCommand((p),"PVWR:%02X%04X%.128s",(ph),(a),(x))
/*!
Send a serial break to reset the device. If the reset was not
successful, the error code will be set to NDI_RESET_FAIL.
*/
#define ndiRESET(p) ndiCommand((p),NULL)
/*!
Get a feature list for this device.
\param mode the desired reply mode
- 0x00 - 32-bit feature summary encoded as 8 hexidecimal digits
- 0x01 - the number of active tool ports as a single digit
- 0x02 - the number of passive tool ports as a single digit
- 0x03 - list of volumes available (see NDI documentation)
- 0x04 - the number of ports that support tool-in-port current sensing
<p>The feature summary bits are defined as follow:
- 0x00000001 - active tool ports are available
- 0x00000002 - passive tool ports are available
- 0x00000004 - multiple volumes are available
- 0x00000008 - tool-in-port current sensing is available
*/
#define ndiSFLIST(p,mode) ndiCommand((p),"SFLIST:%02X",(mode))
/*!
Request status information from the device.
\param format a reply format mode composed of the following bits:
- NDI_CONTROL 0x0001 - control processor information
- NDI_SENSORS 0x0002 - sensor processors
- NDI_TIU 0x0004 - TIU processor
<p>The use of the SSTAT command with the appropriate reply format updates
the information returned by the following commands:
- int \ref ndiGetSSTATControl(ndicapi *pol)
- int \ref ndiGetSSTATSensors(ndicapi *pol)
- int \ref ndiGetSSTATTIU(ndicapi *pol)
<p>This command is not available during tracking mode.
*/
#define ndiSSTAT(p,format) ndiCommand((p),"SSTAT:%04X",(format))
/*! Perform a current test on this port. */
#define ndiTCTST(p,ph) ndiCommand((p),"TCTST:%02X",(ph))
/*!
Put the device into tracking mode.
*/
#define ndiTSTART(p) ndiCommand((p),"TSTART:")
/*!
Take the device out of tracking mode.
*/
#define ndiTSTOP(p) ndiCommand((p),"TSTOP:")
/*! Set default tool configuration prior to testing. */
#define ndiTTCFG(p,ph) ndiCommand((p),"TTCFG:%02X",(ph))
/*!
Request tracking information from the device. This command is
only available in tracking mode.
\param mode a reply mode containing the following bits:
- NDI_XFORMS_AND_STATUS 0x0001 - transforms and status
- NDI_ADDITIONAL_INFO 0x0002 - additional tool transform info
- NDI_SINGLE_STRAY 0x0004 - stray active marker reporting
- NDI_PASSIVE_STRAY 0x1000 - stray passive marker reporting
<p>The TX command with the appropriate reply mode is used to update the
data that is returned by the following functions:
- int \ref ndiGetTXTransform(ndicapi *pol, int ph, double transform[8])
- int \ref ndiGetTXPortStatus(ndicapi *pol, int ph)
- unsigned long \ref ndiGetTXFrame(ndicapi *pol, int ph)
- int \ref ndiGetTXToolInfo(ndicapi *pol, int ph)
- int \ref ndiGetTXMarkerInfo(ndicapi *pol, int ph, int marker)
- int \ref ndiGetTXSingleStray(ndicapi *pol, int ph, double coord[3])
- int \ref ndiGetTXNumberOfPassiveStrays(ndicapi *pol)
- int \ref ndiGetTXPassiveStray(ndicapi *pol, int i, double coord[3])
- int \ref ndiGetTXSystemStatus(ndicapi *pol)
*/
#define ndiTX(p,mode) ndiCommand((p),"TX:%04X",(mode))
/*!
Get a string that describes the device firmware version.
\param n the processor to get the firmware revision of:
- 0 - control firmware
- 1 - left sensor firmware
- 2 - right sensor firmware
- 3 - TIU firmware
- 4 - control firmware with enhanced versioning
*/
#define ndiVER(p,n) ndiCommand((p),"VER:%d",(n))
/*!
Select from the different calibrated operating volumes available to
the device.
\param n the volume to select, see ndiSFLIST()
*/
#define ndiVSEL(p,n) ndiCommand((p),"VSEL:%d",(n))
/*!
Write data from a ROM file into the virtual SROM for the specified port.
\param pol valid NDI device handle
\param ph valid port handle in the range 0x01 to 0xFF
\param filename file to read the SROM data from
\return NDI_OKAY if the write was successful
If the return value is not NDI_OKAY but ndiGetError() returns NDI_OKAY,
then the ROM file could not be read and no information was written
to the device.
This function uses the PVWR command to write the SROM. The total size
of the virtual SROM is 1024 bytes. If the file is shorter than this,
then zeros will be written to the remaining space in the SROM.
*/
ndicapiExport int ndiPVWRFromFile(ndicapi* pol, int ph, char* filename);
/*\}*/
/*=====================================================================*/
/*! \defgroup GetMethods Get Methods
These functions are used to retrieve information that has been stored in
the ndicapi object.
None of these functions communicate with the device itself,
and none of them cause the error indicator to be set.
The DeviceName and DeviceHandle are set when the device is
first opened by ndiOpen().
All other information is set by sending the appropriate command to
the device through ndiCommand() or through one of the command
macros. The information persists until the next time the command is sent.
For example, if the TX command is sent to the device
then the information returned by the methods that start with
GetTX will be set and will subsequently remain unchanged until the next
TX command is sent.
*/
/*! \ingroup GetMethods
Get error code from the last command. An error code of NDI_OKAY signals
that no error occurred. The error codes are listed in \ref ErrorCodes.
*/
ndicapiExport int ndiGetError(ndicapi* pol);
/*! \ingroup GetMethods
Get error code from the last socket command. This provides more detailed information
after calling ndiGetError(...)
*/
ndicapiExport int ndiGetSocketError(ndicapi* pol);
/*! \ingroup GetMethods
Get the name of the serial port device that the device is
attached to.
*/
ndicapiExport char* ndiGetSerialDeviceName(ndicapi* pol);
/*! \ingroup GetMethods
Get the device handle for the serial port that the device is
attached to. This device handle is the value returned by the UNIX open()
function or the Win32 CreateFile() function.
*/
ndicapiExport NDIFileHandle ndiGetDeviceHandle(ndicapi* pol);
/*! \ingroup GetMethods
Get the socket that the device is attached to.
*/
ndicapiExport NDISocketHandle ndiGetSocket(ndicapi* pol);
/*! \ingroup GetMethods
Get the name of the host the device is attached to.
*/
ndicapiExport char* ndiGetHostname(ndicapi* pol);
/*! \ingroup GetMethods
Get the port that the device is attached to.
*/
ndicapiExport int ndiGetPort(ndicapi* pol);
/*! \ingroup GetMethods
Check the current theading mode. The default is 0 (no multithreading).
*/
ndicapiExport int ndiGetThreadMode(ndicapi* pol);
/*! \ingroup GetMethods
Get the current error callback function, or NULL if there is none.
*/
ndicapiExport NDIErrorCallback ndiGetErrorCallback(ndicapi* pol);
/*! \ingroup GetMethods
Get the current error callback data, or NULL if there is none.
*/
ndicapiExport void* ndiGetErrorCallbackData(ndicapi* pol);
/*! \ingroup GetMethods
Get the port handle returned by a PHRQ command.
\param pol valid NDI device handle
\return a port handle between 0x01 and 0xFF
<p>An SROM can be written to the port handle wit the PVWR command.
*/
ndicapiExport int ndiGetPHRQHandle(ndicapi* pol);
/*! \ingroup GetMethods
Get the number of port handles as returned by a PHSR command.
\param pol valid NDI device handle
\return an integer, the maximum possible value is 255
*/
ndicapiExport int ndiGetPHSRNumberOfHandles(ndicapi* pol);
/*! \ingroup GetMethods
Get one of the port handles returned by a PHSR command.
\param pol valid NDI device handle
\param i a value between 0 and \em n where \n is the
value returned by ndiGetPHSRNumberOfHandles().
\return a port handle between 0x01 and 0xFF
<p>The PHINF command can be used to get detailed information about the
port handle.
*/
ndicapiExport int ndiGetPHSRHandle(ndicapi* pol, int i);
/*! \ingroup GetMethods
Get the information for a port handle returned by a PHSR command.
\param pol valid NDI device handle
\param i a value between 0 and \em n where \n is the
value returned by ndiGetPHSRNumberOfHandles().
\return a 12-bit bitfield where the following bits are defined:
- NDI_TOOL_IN_PORT 0x01 - there is a tool in the port
- NDI_SWITCH_1_ON 0x02 - button 1 is pressed
- NDI_SWITCH_2_ON 0x04 - button 2 is pressed
- NDI_SWITCH_3_ON 0x08 - button 3 is pressed
- NDI_INITIALIZED 0x10 - tool port has been initialized
- NDI_ENABLED 0x20 - tool port is enabled for tracking
- NDI_CURRENT_DETECT 0x80 - tool sensed through current detection
<p>The PHINF command can be used to get detailed information about the
port handle.
*/
ndicapiExport int ndiGetPHSRInformation(ndicapi* pol, int i);
/*! \ingroup GetMethods
Get the 8-bit status value for the port handle.
\param pol valid NDI device handle
\return a an integer composed of the following bits:
- NDI_TOOL_IN_PORT 0x01 - there is a tool in the port
- NDI_SWITCH_1_ON 0x02 - button 1 is pressed
- NDI_SWITCH_2_ON 0x04 - button 2 is pressed
- NDI_SWITCH_3_ON 0x08 - button 3 is pressed
- NDI_INITIALIZED 0x10 - tool port has been initialized
- NDI_ENABLED 0x20 - tool port is enabled for tracking
- NDI_CURRENT_DETECT 0x80 - tool sensed through current detection
<p>The return value is updated only when a PHINF command is sent with
the NDI_BASIC (0x0001) bit set in the reply mode.
*/
ndicapiExport int ndiGetPHINFPortStatus(ndicapi* pol);
/*! \ingroup GetMethods
Get a 31-byte string describing the tool.
\param piol valid NDI device handle
\param information array that information is returned in (the
resulting string is not null-terminated)
\return one of:
- NDI_OKAY - information was returned
- NDI_UNOCCUPIED - port is unoccupied or no information is available
<p>The returned string will not be null-terminated by default. You
must set information[31] to 0 in order to terminate the string.
If the port is unoccupied then the contents of the \em information