Precision Location Ultra Wideband System (PLUS™) Precision Real-Time Location System System Manual System Manual Precision Real-Time Location System P320-0239 July 2008 Time Domain Corporation Cummings Research Park 330 Wynn Drive, Suite 300 Huntsville, AL 35805 USA http://www.timedomain.com Tel: +1.256.922.9229 +1.888.826.8378 Fax: +1.256.922.
PLUS System Manual Nondisclosure Provisions This manual is confidential and is governed by the terms of the Nondisclosure Agreement and the Partner Agreement currently in effect between the parties. Copyright ©2001-2008 Time Domain Corporation. All rights reserved. Trademarks Time Domain® and PulsON® are registered trademarks of Time Domain Corporation. Ethernet® is a registered trademark of Xerox Corporation. ―PulsON Triangle‖ logo and PLUS™ are trademarks of Time Domain Corporation.
PLUS System Manual 3 Table of Contents 1. 1.1 OVERVIEW .................................................................................................................10 Manual Contents ................................................................................................................... 11 1.2 PLUS System Products ......................................................................................................... 11 1.2.1 Synchronization Distribution Panel ...........................
PLUS System Manual 2.4.7.3 Tracking Cells ............................................................................................................ 30 2.4.7.4 Maps .......................................................................................................................... 33 2.4.7.5 Group Setup Guidelines ............................................................................................. 33 2.4.8 Assigning Reader Groups ..........................................................
PLUS System Manual 5 3.4.2.2 Reader Responses ....................................................................................................... 63 3.4.3 Reader Alarms..................................................................................................................... 64 4. PLUS LOCATION SOFTWARE LIBRARY .................................................................66 4.1 Introduction ...............................................................................................
PLUS System Manual 5.2 Menu Bar ............................................................................................................................. 102 5.2.1 File .................................................................................................................................... 102 5.2.2 View ................................................................................................................................. 104 5.2.3 Settings ......................................
PLUS System Manual 7 Table of Figures Figure 1-1 : PLUS SDP, Readers, and Tags ......................................................................................... 10 Figure 1-2 : PLUS Interfaces ............................................................................................................... 10 Figure 2-1: Hardware Connections for a Four-Reader System ........................................................... 14 Figure 2-2: Hardware Placement for a Four-Reader System..................
PLUS System Manual Figure 2-32: Calibration Assist Mode .................................................................................................. 41 Figure 2-33: Tag Statistics ................................................................................................................... 42 Figure 2-34: TDOA Statistics .............................................................................................................. 42 Figure 2-35: Tag-Reader Associations .......................
PLUS System Manual 9 Figure 5-7: Set Trail Length Dialog ................................................................................................... 105 Figure 5-8: TDOA Statistics Dialog .................................................................................................. 106 Figure 5-9: Tag Statistics Dialog ....................................................................................................... 107 Figure 5-10: Position Statistics Dialog .............................
Overview PLUS System Manual 1. Overview The Precision Location Ultra Wideband System (PLUS) is a state-of-the-art, real-time location system (RTLS) utilizing ultra wideband technology. The PLUS RTLS provides unparalleled tag capacity and precision location capability. The contents of this manual are applicable to Release 2.0 of the PLUS hardware and software. Users of Release 1.
PLUS System Manual 1.1 Overview 11 Manual Contents The sections of this document are organized to allow system installers, programmers, and users to easily find the information they need. Section 1 provides an introduction to the PLUS system, with a summary of the PLUS products and peripherals. All users should start with this introduction to familiarize themselves with the system. Section 2 is the System Installation reference for the system.
Overview 1.2.3 PLUS System Manual Asset Tag The PLUS Tag is an ultra wideband active transmitter. Once per second, the Tag transmits a short packet containing a unique serial number. One or more PLUS Readers receive this transmission and pass the Tag data and Time of Arrival (TOA) to a Location Engine which calculates the precise location of the Tag. The PLUS Tag is small and durable, with a plastic housing that allows it to be attached to assets or people.
PLUS System Manual Overview 13 One 10/100/1000 Mbps card for LAN connectivity 1.3.3 Ethernet Cable The SDP and Reader components must be connected with 24-gauge CAT 5e shielded cable or better. This grade of cable is required for readers to perform according to specifications. Avoid breaking cable continuity by routing through breakout or junction blocks. If it is necessary to break cable continuity, shield integrity should be maintained across the interconnect.
System Installation PLUS System Manual 2. PLUS System Installation This section of the PLUS System Manual describes the setup and configuration steps that are required for a PLUS installation. Most of the setup steps are the same for a small or large installation, but large installations a degree of planning and testing that can be minimized in smaller installations.
PLUS System Manual 2.1 System Installation 15 Pre-Installation Site Survey Prior to installing a system, the installation site must be inspected and a plan developed to determine the number and locations of hardware components that will be needed. There are several planning steps and rules of thumb that should be applied when evaluating an installation site: 1) Obtain an accurate, electronic format building plan.
System Installation PLUS System Manual Figure 2-3: Equilateral Triangle Reader Geometry As shown in Figure 2-4, right triangles can also work well but will have a no-solution region close to the right-angle vertex. Figure 2-4: Right Triangle Reader Geometry 7) When selecting Reader mounting locations, be sure that the area is accessible and not blocked by light fixtures, sprinkler heads, exit signs, etc. Select areas where Readers/Antenna assemblies can be mounted at heights between 6’ and 15’.
PLUS System Manual 2.2 System Installation 17 Reader Placement and Wiring Diagram After identifying the locations where Readers will be installed, you should develop a diagram that illustrates where Readers will be placed and how they will be connected to each other and to the SDP. Use the building floor plan to mark Reader locations, label each wiring chain, and clearly identify which Reader locations are at the beginning, middle, and end of each chain.
System Installation 2.3 PLUS System Manual Installation Overview The next section of this manual covers the physical installation and checkout of the system. When installing the PLUS hardware, the following steps should be followed to ensure correct system operation. Use this list as a checklist to make sure that all the necessary configuration steps have been followed. Each item on the checklist is described in detail below. a) b) c) d) e) f) g) h) i) j) k) l) m) n) o) p) q) 2.3.
PLUS System Manual 2.3.3 System Installation 19 Configuring Reader and Location Engine IP Addresses Reader Static IP and Dynamic IP Addresses By default, Readers are configured to request an IP address from a DHCP server each time they are booted. If you plan to use dynamic IP assignment, the server connected to your tracking network must host a DHCP server.
System Installation PLUS System Manual Figure 2-7: Reader IP Address Configuration Figure 2-8: Solver IP Address Configuration Proprietary Information: Do not disclose unless authorized under a Nondisclosure Agreement and the Partner Agreement.
PLUS System Manual 2.3.4 System Installation 21 Ceiling Installation of Readers and Antennas The following steps describe how to connect a Reader to an Antenna and install the assembly into the ceiling. Start by installing the first Reader in the chain from the SDP, and proceed down the chain to the last Reader. This will allow Readers to be powered and their operation verified as they are installed. 2.3.4.
System Installation PLUS System Manual 5. Tilt the drop panel and insert it into the frame opening. Lower the panel so that it is seated evenly on the Antenna frame. 6. Connect the proper Ethernet cable to SYNC IN port of the Reader. Verify that the cable snaps into the connector firmly and the Reader powers on (via Ethernet LEDs). If there are additional Readers in the chain, connect the proper Ethernet cable to the SYNC OUT port of the Reader.
PLUS System Manual System Installation 23 IMPORTANT: Do not attempt to use the system with an unterminated Ethernet cable plugged into the SYNC OUT port of a Reader, or unstable operation can result. An Ethernet cable plugged into the SYNC OUT port of a Reader must be plugged into the SYNC IN port of another Reader to be properly terminated. SDP U n t e r m in a t e d C a b le Reader Reader Figure 2-14: Unterminated Ethernet Cables 2.3.
System Installation 2.3.6 PLUS System Manual Server Setup and Software Installation The following steps describe the process of connecting to a server through an Ethernet switch, configuring server network settings, and installing the PLUS software. 2.3.6.1 Connecting the SDP, Ethernet Switch, and Server The Ethernet traffic on each SDP ―LAN IN‖ port is isolated from all other ―LAN IN‖ ports and must be routed through an Ethernet switch to the server.
PLUS System Manual 2.3.6.3 System Installation 25 Server Firewall Settings If the server on which you will be running the Visualizer has a firewall enabled, be sure that the firewall settings will allow traffic from the subnet assigned to the Readers. For convenience, you may wish to temporarily disable the firewall until you have verified that you are receiving traffic from the Readers correctly.
System Installation 2.4 PLUS System Manual Configuring the System Using Visualizer This section describes how to use the Visualizer application to configure the data source for the Visualizer, check for reliable Reader communications, enter Reader, Group and Map configuration data into the system, and enter a floor plan. 2.4.1 Workflow Visualizer is the recommended tool for configuring a new PLUS installation, making changes to an existing installation, or troubleshooting an installation.
PLUS System Manual 2.4.2 System Installation 27 PLUS Visualizer Software Installation Insert the PLUS Visualizer Setup CD and follow the InstallShield Wizard instructions. If you are updating a previous installation, use the ―Upgrade‖ option. After installation is complete, run the PLUS Visualizer application. Figure 2-18: Visualizer Application Proprietary Information: Do not disclose unless authorized under a Nondisclosure Agreement and the Partner Agreement.
System Installation 2.4.3 PLUS System Manual Set Data Input Under the Settings menu, open the Set Data Input… selection. Select the IP Address radio button. Pull down the list box to select the IP address for the NIC that is receiving tracking network data and click the OK button (See Figure 2-19: Set Data Input). The Message Frame will update with a list of Readers and Tags that are added to the system. Figure 2-19: Set Data Input 2.4.
PLUS System Manual 2.4.5 System Installation 29 Setting English/Metric Units Under the Settings menu, select 2D MapView Settings…. In the MapView Settings window, select English or Metric according to which units you will use to enter Reader and Tag survey data. Figure 2-21: Setting English/Metric Units You may change other MapView settings to make the Visualizer easier to view during installation.
System Installation 2.4.7 Reader Groups 2.4.7.1 Reader Groups Overview PLUS System Manual The ability to create Reader Groups is an important feature of the 2.0 Location Engine. Establishing multiple Reader Groups allows a large installation to be divided into small sections, each of which acts as an independent location system. Managing a PLUS system as a set of small, independent systems is much easier than trying to work with one large group of Readers.
PLUS System Manual System Installation 31 Figure 2-23: Tracking Cell for a Four-Reader Group When tracking cells are defined for both a group and a map, Tag solutions are tested against the group tracking cells first If the solution passes the group tracking cell, it is then tested against the map tracking cell Group tracking cells that share a border with map tracking cell should be defined with extra margin outside of the boundary.
System Installation PLUS System Manual Figure 2-24: Group Tracking Cell with Boundary Margin With some Reader geometries (such as Readers in a line), when the Location Engine attempts to calculate a Tag position, it produces two results. Only one result represents the actual position. The other result is a mirror-image, or ambiguous solution. By defining a tracking cell in these cases, the Location Engine can filter the false solution.
PLUS System Manual 2.4.7.4 System Installation 33 Maps Each Reader group is associated with a map. Multiple groups may be assigned to the same map, but a group can be assigned to only a single map. All of the Readers on a given map have a common coordinate system and origin. When a new group is created, it is assigned to Map 0 by default. Visualizer allows you to import and scale a floorplan image file for each map.
System Installation PLUS System Manual The tracking cell snap feature is primarily intended for use with Map tracking cells. Using a snap setting with group tracking cells may result in undesired snap behavior in the interior of a building. Use architectural features of a building to break the system into meaningful groups. Hallways and intersections make good boundaries between groups. Use Group 0 as a ―stockpile‖ of unassigned Readers.
PLUS System Manual System Installation 35 Figure 2-27: Group Configuration Window Under the Group/Solver Parameters frame: Check the 0D, 1D, and 2D boxes to select the type of location data this group will provide. 0D and 2D are selected by default for a newly created group. Sort type should be set to TOA Sort. There is one exception – a non-calibrated group of Readers configured for 0D only should use RSSI Sort instead. Check the ―Group is enabled‖ box to enable tracking with this group.
System Installation PLUS System Manual Click the Display current tracking cell box to show the Group tracking cell on the 2D MapView. You may enter a snap distance for the group tracking cell. If a snap distance is defined, Tags that are located outside the tracking cell but less than the snap distance from the tracking cell will be shown on the boundary of the tracking cell. If tag solutions are outside of the snap distance, they will be discarded.
PLUS System Manual System Installation 37 Under the Member Groups frame, click on a Reader group and use the direction arrows to add or remove it from the selected map. Under the Tracking Cell frame: To define a tracking cell for the map, click the Enter Polygon button in the Tracking Cell frame. Click on the map display to place vertices of the polygon. As each vertex is placed, the polygon will automatically draw a line to the original vertex to close the area.
System Installation 2.4.12 PLUS System Manual Cable Length and Termination Settings With the 2.0 Reader, cable length and termination settings are automatic, and these columns are for user information only. 2.4.13 System Configuration Files Under the File menu, select Save Config As… to create a new configuration folder. A PLUS configuration consists of two files. Trackerconfig.txt is used by the Location Engine to store survey information, calibration data and other system parameters.
PLUS System Manual 2.5 System Installation 39 System Calibration The following section describes the process of calibrating the PLUS system. The purpose of calibration is to remove the time delays introduced by the varying length cables run to each Reader. Because the Location Engine calculations are based on the Tag signal time of arrival to each Reader, it is necessary to remove these additional timing delays to produce accurate location results. With the 2.
System Installation PLUS System Manual 1 2 4 A B 3 5 Figure 2-30: Inadequate Calibration Tag Coverage 1 2 A 4 B 3 5 Figure 2-31: Adequate Calibration Tag Coverage Select locations for Calibration Tags where they can be heard reliably by as many Readers as possible. However, be careful to avoid paths that are subject to blockage, reflections, and grazing angles through walls. Mount the Calibration Tags horizontally whenever possible.
PLUS System Manual System Installation 41 to have a visual reference on the map. If you decide to keep the tag in this location, don’t forget to update the survey with accurate information! Open the Calibration window by clicking the Calibrate button in the tool bar, then enable the Calibration Assist mode from the Options menu (Figure 2-32).
System Installation PLUS System Manual Figure 2-33: Tag Statistics Next, check the TDOA stability, which is very important for reliable calibration. Open the TDOA Stats window under the View menu. Select the Tag ID and clear the statistics. You may also wish to select a specific Reader using the Filter by reader pull-down box to reduce the amount of data presented. Allow the statistics to accumulate for several seconds, and then monitor the TDOA values shown in the Max Peak-Peak column.
PLUS System Manual System Installation 43 use a given Calibration Tag reliably. Next, you should enter your list of reliable Tag-Reader combinations into Visualizer to enable robust calibration. Click the Calibrate button to open the Calibration window. Under the Options menu, open the Set tag-reader associations selection. Use the pull-down lists for Readers and Tags to add the desired combinations to the list.
System Installation 2.5.4 PLUS System Manual Calibration Tag Survey and Configuration After the location of a Calibration Tag has been finalized, survey its position using the same approach that was used to survey Reader locations. Record the Tag ID and X, Y, Z coordinates for each Calibration Tag. Continue to place and verify Calibration Tags until one or more groups of Readers has been covered with adequate overlap.
PLUS System Manual System Installation 45 Figure 2-38: Calibration Window 4) Click the Start button to calibrate the system. 5) While the system is calibrating, the progress bar will increment and the control button will display Stop. When calibration is complete, a popup window will provide results for the calibration. If calibration is successful, you should apply the calibration results. A calibration report will provide status of the calibrated readers.
System Installation PLUS System Manual Figure 2-40: Calibration Report – All Readers Calibrated 6) If calibration fails, click No on the Calibration Completed popup, and check the calibration report to determine which Readers failed. Re-check the statistics (RX%, RSSI, and TDOA) for any Readers that failed to calibrate. Adjust tag positions or add new calibration Tags if necessary to provide adequate coverage for the failed Readers.
PLUS System Manual System Installation 47 Figure 2-43: No Stitching to Reader Rf90 7) After each group is successfully calibrated, save the current configuration containing the new calibration results using the File menu Save Config or Save Config As… selections. The next time Visualizer is run, it will restore the saved calibration settings without the need to repeat the calibration process. Repeat the calibration process until all groups in the system are calibrated.
System Installation 2.6 PLUS System Manual Monitoring Location Performance This section describes Visualizer features and settings that are commonly used to monitor the tracking performance of the system. A more complete description of Visualizer features is provided in Section 5 PLUS Visualizer of this manual. 2.6.1 Viewing Calibration Tags After calibration, you may wish to compare the calculated Calibration Tag position to the surveyed Calibration Tag position.
PLUS System Manual System Installation 49 Figure 2-45: Tag Statistics Pull down the Select Tag box to select the ID of the Tag you wish to monitor. Click the Reset button, and allow statistics to accumulate. The received statistics for each Reader in the system can then be observed. For a Tag in a given location, the nearest Readers are most significant in calculating a position. The close-by Readers should show good statistics.
System Installation PLUS System Manual Figure 2-46: Intersection of TDOA Lines at the Tag Location Under the Visualizer View menu, select TDOA Stats to observe the TDOA values between each pair of Readers. Figure 2-47: TDOA Statistics Pull down the Select Tag box to select the Tag ID you wish to observe. Click the Reset Stats button to clear the TDOA statistics for that Tag. Allow the statistics to accumulate. The TDOA statistics should be observed for a stationary Tag.
PLUS System Manual System Installation 51 TDOA statistics are displayed in nanoseconds. The most significant results in the TDOA Statistics window are the Peak-Peak and Max Peak-Peak columns. The Peak-Peak column shows the peak variation in the TDOA value over the last 1024 values. The Max Peak-Peak column shows the maximum TDOA variation seen since the statistics were reset.
System Installation PLUS System Manual To disable the Averaging Filter, enter a value of 0 for Moving average positions. To enable the Averaging Filter, enter a value of 2 or more. The maximum number of moving average positions allowed is 20. Therefore, the number of positions must be between 2 and 20. NOTE that using 1 position has no filtering effect. 2.6.
PLUS System Manual 2.7 System Installation 53 Troubleshooting Reader Communications For cases where the Visualizer is unable to see data from the Readers, follow the troubleshooting procedure below. Check that discovery packets are being received from the Readers. Under the Reader List View, determine if the Last Comms timer is exceeding ten seconds for the Reader(s) in question.
System Installation PLUS System Manual Figure 2-52: Command Window Figure 2-53: Check for Port 11000 Conflicts 9) If the Reader responds to the ping request, but data is still not received by the Visualizer, check and correct the Location Engine IP address on the Reader as described in section 2.3.3 Configuring Reader and Location Engine IP Addresses. 2.7.2 Reader Connectivity but No Tag Traffic 1. Place a known working Tag in proximity to the Reader in question.
PLUS System Manual 2.8 System Installation 55 Reader Installation Worksheet MAC Address IP Address Location Notes Reference Walls X Offset Y Offset (m) (m) Z (m) SDP to Reader X Coordinates Y Coordinates Cable Length (m) (m) (m) Proprietary Information: Do not disclose unless authorized under a Nondisclosure Agreement and the Partner Agreement.
System Installation 2.9 PLUS System Manual Calibration Tag Installation Worksheet Tag ID Location Notes Reference Walls X Offset (m) Y Offset (m) Z (m) X Coordinates (m) Proprietary Information: Do not disclose unless authorized under a Nondisclosure Agreement and the Partner Agreement.
PLUS System Manual Reader Data Interface 57 3. PLUS Reader Data Interface 3.1 Overview The PLUS Reader has a 100Base-TX Ethernet connection that allows the Reader to communicate with other components in the system. This section describes the Tag packet data sent by the Reader over the Ethernet interface. The Reader will also respond to ASCII commands over the Ethernet interface. These commands and the Reader responses will be described.
Reader Data Interface 3.2.2 PLUS System Manual Location Engine IP Address The default Reader configuration assumes that the location engine IP address is the first IP address in the subnet. For example, if the acquired IP lease is 10.25.67.100 and the subnet mask is 255.0.0.0, then the Reader software assumes the location engine IP address is 10.0.0.1. The Reader may also be configured with a static location engine IP address.
PLUS System Manual Reader Data Interface 59 Figure 3-2: changeIp and solverIp Commands 3.4 Detailed Interface Description At startup, the Reader listens for a connection on TCP port 11001. The Reader can be controlled by sending ASCII commands over this socket. Also, at startup (and subsequently when no Tag transmission has been heard within 10 seconds), the Reader broadcasts a discovery TOA packet to UDP port 11000 to announce its presence.
Reader Data Interface PLUS System Manual Each field in the packet is discussed in detail below: Reader ID – The Reader’s 48-bit MAC address Version – 4-bit field that denotes the version of the data format. This document describes version 2. Each time the format of the TOA packet changes, the version number will also change. BS – 2-bit battery status reported by the Tag BN – 2-bit button event field from the Tag payload. A button event of 0 means that the button is not pressed.
PLUS System Manual char toaPcnt; Reader Data Interface 61 /* TOA status and preamble count */ }; The tagId field in the structure above will be received in reverse byte order on little endian machine architectures (e.g., Intel-based PCs) and will need to be byte-swapped. The Reader sends a special form of the TOA packet, called a discovery TOA packet, to the network broadcast address after initial startup.
Reader Data Interface PLUS System Manual Command Meaning RX 1 Enable the Reader. This causes the Reader to start listening to Tag packets. The Reader is automatically enabled at startup. RX 0 Disable Reader. The Reader will stop listening for Tag packets. CAL 1 Enable power to Calibration Tag. CAL 0 Disable power to Calibration Tag. Power to the Calibration Tag is disabled at startup. IP DHCP Configure the Reader to acquire its IP address via DHCP.
PLUS System Manual 3.4.2.2 Reader Data Interface 63 Reader Responses Several of the commands listed in the previous section cause the Reader to reply with a response string. These responses are discussed below. SENDSTATUS The SENDSTATUS command causes the Reader to send its current control settings.
Reader Data Interface PLUS System Manual In this example, the Reader replied with the following statistics: 1000 packets received correctly, 5 packets received with incorrect CRC, 2 false detections, no FIFO overflows, 10 packets received that produced bad TOA calculations, an uptime of 1000000 seconds, a temperature of 30.5 degC, the PLL was never unlocked, and no sync marker errors have occurred. Internally, the Reader keeps all statistics in unsigned 32-bit integers.
PLUS System Manual Reader Data Interface 65 The bit definitions in the alarm status and alarm enable words are as follows: Bit Position Alarm Source Meaning 0 PLL Lock Lost 1 Reboot 2 3-31 Sync Marker Error Reserved The Reader lost synchronization with the SDP. The Reader will need to be recalibrated. The Reader has rebooted. When a PLUS system is initially powered on, all readers will report this alarm and the alarm should be cleared.
Location Software Library PLUS System Manual 4. PLUS Location Software Library 4.1 Introduction This section documents the functions, properties, and events provided by the PLUS™ Tracker OCX software layer. Time Domain customers interested in developing software to utilize TOA data from the PLUS Readers or recorded data from Time Domain’s tracking component can do so via this OCX library.
PLUS System Manual 4.2 Location Software Library 67 Tracker Object Overview The PLUS Location Software OCX contains a single object, called Tracker. The Tracker Object performs the following functions: 1. Receives data from the Readers either over Ethernet (live data), or from a logfile (recorded/simulated data). 2. Provides access to TOA message data through a COM event. 3.
Location Software Library PLUS System Manual Maps can be used to provide a common coordinate system for all Readers that are part of the Map. Maps are useful in multi-floor or multi-building installations. Maps must not overlap. To avoid this, a Reader cannot be assigned to Groups in a way that allows the Reader to appear in more than one Map. The Location Software supports limiting a Tag position to allowable regions, called Tracking Cells.
PLUS System Manual Location Software Library 69 Object includes a rich API for configuring and monitoring the Location Software, most applications only need to use a few of the API features. Section 4.5.1 discusses the features of the API that are commonly used by all applications. Section 4.5.2 discusses the more advanced features of the API, including configuration and additional system monitoring features. 4.5.
Location Software Library 4.5.1.4 PLUS System Manual IsTOAMessageQueueStarted Function public virtual int IsTOAMessageQueueStarted() Returns nonzero if the TOA message queue is started. Returns 0 – TOA message queue not started Nonzero – TOA message queue is started 4.5.1.
PLUS System Manual Location Software Library 71 bestReaderIdLow, bestReaderIdHi The best Reader is the first TOA of the last bundle used to produce a solution. It is provided primarily as an aid in debugging. 4.5.1.
Location Software Library PLUS System Manual received from a Reader. Once a Reader alarm event has fired, the Location Software will wait a configurable amount of time before sending another Reader alarm event. A Tag timeout alarm is fired when the Location Software has not received a Tag transmission in a configurable amount of time. 4.5.2.1.1 SetTrackerAlarmTimeout Function public virtual int SetTrackerAlarmTimeout( int alarmType,, int alarmTimeoutValue) This function sets alarm timeouts.
PLUS System Manual 4.5.2.2 Location Software Library 73 Calibration These functions, properties and events are used to control calibration of a Group. 4.5.2.2.1 ControlAutoCal Function public virtual int ControlAutoCal( int groupId, int calPeriod, int calFlags) Starts auto calibration on a group. The function can also be used to cancel a calibration in progress. groupId is the ID for the group.
Location Software Library 4.5.2.2.3 PLUS System Manual GetAutoCalGroupEntryInfo Function public virtual int GetAutoCalGroupEntryInfo( int readerIdLow, int readerIdHigh, int groupId, double out readerGroupCalValue, int out calReaderGroupStatus) This function retrieves the current auto calibration data for a group entry. A calibration can be in progress, or a calibration can have completed successfully, or completed and failed. groupId is the ID for the group.
PLUS System Manual 4.5.2.2.5 Location Software Library 75 GetNextCalIncludeExcludeEntry Function public virtual int GetNextCalIncludeExcludeEntry( int int int int int int readerIdLow, readerIdHigh, tagId, out nextReaderIdLow, out nextReaderIdHigh, out nextTagId) Retrieves the next calibration include/exclude entry in the list. To get the first entry in the list, pass 0 in for the readerIdLow, readerIdHi, and tagId parameters. readerIdLow is the lower portion of Reader ID.
Location Software Library state PLUS System Manual 0 = calibration state unknown, may never have run a calibration this group 1 = calibration in progress 2 = calibration successful 3 = calibration failed. 4.5.2.3 Configuration Storage This function is used to store the configuration of the Location Software to a file. The counterpart to this function, ReadConfig, was discussed previously in the Commonly Used Functions section. 4.5.2.3.
PLUS System Manual Location Software Library 77 1 - group enabled. groupFlags is a bit field that controls group characteristics Bit 0 - Group Tracking Cell is enabled Bit 3 - Co-linearity check disabled. Bit 4 - Group can be calibrated – currently this bit is ignored. Bit 5 - RSSI Sorting, used for groups that only provide 0D or presence detect positions and the Readers in that group are not synchronized allowedSolverFlags is a bit field that controls which type of solutions a group can produce.
Location Software Library PLUS System Manual 1 - group enabled. groupFlags is a bit field that controls group characteristics Bit 0 - Group Tracking Cell is enabled Bit 3 - Co-linearity check disabled. Bit 4 - Group can be calibrated – currently this bit is ignored. Bit 5 - RSSI Sorting, used for groups that only provide 0D or presence detect positions and the Readers in that group are not synchronized allowedSolverFlags is a bit field that controls which type of solutions a group can produce.
PLUS System Manual Location Software Library 79 Removes a group from the tracker's database. The group must exist or an error is returned. Group 0 cannot be deleted. It is created at startup to handle old configuration files and Readers not in the current configuration. groupId is the ID for the group. Returns 0 - Success Less than zero - Invalid group ID 4.5.2.5 Group Entry Configuration The functions in this section are used to add, remove, and configure Reader entries within the Groups. 4.5.2.5.
Location Software Library 4.5.2.5.2 PLUS System Manual GetGroupEntry Function public virtual int GetGroupEntry( int readerIdLow, int readerIdHigh, int groupId, double out x, double out y, double out z, int out readerState, double out calibrationValue, int out calibrationValid,) This function retrieves a Reader entry from a group. The Reader entry must already exist or an error is returned. readerIdLow is the lower four bytes of the Reader MAC address of the requested Reader entry.
PLUS System Manual Location Software Library 81 nextReaderIdHi is the upper two bytes of the next Reader MAC address. Returns 0 - Success Less than zero – No Reader higher than current Reader (current Reader is the last Reader in the group). 4.5.2.5.4 RemoveGroupEntry Function public virtual int RemoveGroupEntry( int groupId, int readerIdLow, int readerIdHigh) This function removes a Reader from a group. The Reader entry must exist or an error is returned. groupId is the ID for the group.
Location Software Library PLUS System Manual replaced with the nearest point on the tracking cell boundary. If the computed distance is larger that this value, the position is discarded. bufferSize is the number of values in the tracking cell. Each point requires two values, an X and Y value. For example if four points define a tracking cell then the buffer would contain eight values. trackingCellPoints is a buffer containing the points that define a tracking cell.
PLUS System Manual 4.5.2.7.1 Location Software Library 83 AddOrUpdateCalTag Function public virtual int AddOrUpdateCalTag( int tagId, double x, double y, double z, int *groupIdList, int groupIdListLength) This function adds a calibration Tag to the tracker's Calibration Tag database. If the Tag already exists, it updates the Tag's configuration. Calibration Tags are necessary for calibrating the Readers. They are always at fixed positions specified by X, Y, and Z. tagId is the ID of Tag.
Location Software Library PLUS System Manual Returns 0 - Success; the Tag exists and the x, y and z coordinates have been returned. Less than zero - The Calibration Tag does not exist in the database. 4.5.2.8 Tag Configuration The functions in this section are used to configure the Location Software’s internal Tag database. 4.5.2.8.1 AddOrUpdateTag Function public virtual int AddOrUpdateTag( int tagId, double nominalZheight) Adds a Tag (non-Calibration Tag) to the Tag database.
PLUS System Manual 4.5.2.8.3 Location Software Library 85 GetNextTag Function public virtual int GetNextTag( int currentTagId, int out nextTagId) Retrieves next Tag ID given a Tag ID. The next Tag ID is the next higher numbered Tag. To retrieve the first (lowest numbered) Tag ID, pass -1 in the currentTagId parameter. Returns 0 - Success Less than zero – No Tag ID higher than currentTagId (currentTagId is the last Tag ID). 4.5.2.8.
Location Software Library PLUS System Manual calculated. bestReaderIdLow, bestReaderIdHi The best Reader is the first TOA of the last bundle used to solve. This is include primarily as a debugging aid. positionFom is a figure of merit (quality metric) for the position. The range is 0 to 100, 0 being worst and 100 being best position metric. Returns 0 – Success Less then zero – Unknown Tag ID or No solution available 4.5.2.8.
PLUS System Manual Location Software Library 87 Parameter ID Description Type Units Default Value 2 Nominal Tag Z height double m 1 8 Moving average filter depth integer N/A 3 9 Tag speed limit filter double m/s 2 The nominal Tag Z height is the default Tag height assumed by the solver. This value can be overridden on a perTag basis with the AddOrUpdateTag function. The Tag speed limit filter and moving average filter can be disabled by setting them to a value of 0.
Location Software Library PLUS System Manual Returns 0 – Data source is not a valid IP address Nonzero – Data source is an IP address 4.5.2.10.2 SetInput Function public virtual int SetInput( int input) Selects either raw file or live data (IP data) as input to tracker input 1 = IP Data – Live data from Ethernet interface. 0 = Replay data from a raw file. Returns 0 – Success. Less that zero - Failed 4.5.2.10.
PLUS System Manual Location Software Library 89 4.5.2.10.5 playbackMode Property public virtual int playbackMode { set; get; } This function sets the playback options for raw log files. Has no effect on live data streaming. The playbackMode must be set before StartTOAMessageQueue is called. Bit 0 – if set, playback is not paced by the timestamp recorded for each logged TOA message, i.e. the file is played back at maximum speed.
Location Software Library PLUS System Manual 4.5.2.11 Debug and Troubleshooting The functions, properties, and events in this section may be useful in troubleshooting installation problems. In particular, the outputLogFileName property controls logging of raw TOA data to a file. 4.5.2.11.1 outputLogFileName Property public virtual string outputLogFileName { set; get; } If empty, no data is logged. If a filename is specified, TOA messages are saved to that file.
PLUS System Manual Location Software Library 91 This event is fired whenever a new TOA message is received. Timestamp is the time as returned by the Windows API function GetTickCount() at the time the TOA is received. 4.5.2.12 Miscellaneous Miscellaneous functions include a convenient way to send commands to a Reader and a routine to flush the TOA message queue. 4.5.2.12.1 FlushTOAMessageQueue Function public virtual void FlushTOAMessageQueue() Removes all pending TOA messages in the queue.
Location Software Library PLUS System Manual 4.5.2.13.2 NewTag Event public virtual void NewTag( int int int int tagId, readerIdLow, readerIdHi, seqNum) This event is fired whenever a new Tag is detected. 4.5.2.13.3 NewGroupEntry Event public virtual void NewGroupEntry( int int int int readerIdLow, readerIdHi, groupId, state) This event is fired whenever a Reader entry is added to a group.
PLUS System Manual 4.6 Location Software Library 93 Raw Data Log File Formats The file itself is actually divided into two sections – Configuration and Data. By capturing both the system configuration and the raw TOA messages, the information needed for playback is encapsulated into one logfile for use as a data input source. 4.6.1.1 Configuration ## CONFIGURATION # 080711,152111,13780.5, VERSION 2.0.
Location Software Library GROUP 1, 1, # READER: ID (MAC address) PLUS System Manual 0x10, 0.00 Z, Calibration, 13.41000, 36.92000, 2.750000, 1236.00000, 1, 1 READER 0x50c216a541, 13.47000, 45.48000, 2.750000, 72.9500000, 1, 1 READER 0x50c216a56f, 29.11000, 35.09000, 2.750000, 1015.09000, 1, 1 READER 0x50c216a590, 15.92000, 17.60000, 2.750000, -454.53000, 1, 1 READER 0x50c216aeef, 0.220000, 14.01000, 2.750000, -362.67000, 1, 1 READER 0x50c216aef7, 9.770000, 27.97000, 2.
PLUS System Manual Location Software Library 95 CALTAG 0xa3b, 3.940000, 25.99000, 2.200000, CALTAG 0xa4f, 15.54000, 13.33000, 2.200000, CALTAG 0xa5b, 8.570000, 3.900000, 2.200000, CALTAG 0xa68, 36.00000, 6.200000, 2.200000, CALTAG 0xa75, 24.26000, 13.33000, 2.200000, CALTAG 0xa7f, 3.820000, 5.120000, 2.200000, # Solver, ParametersId, Parameter, SolverId SOLVER 2, 0.76, # default Z Height SOLVER, 6, 0.
Location Software Library PLUS System Manual 0.125, 0x0050c216af90, 1, 3, 0, 57, 0, 0, 0x00000995, 176, 38, 128, 20 0.125, 0x0050c216af6c, 1, 3, 0, 57, 0, 0, 0x00000995, 49, 231, 82, 18 0.125, 0x0050c216afdf, 1, 3, 0, 57, 0, 0, 0x00000995, 7, 212, 86, 18 0.125, 0x0050c216afba, 1, 3, 0, 57, 0, 0, 0x00000995, 222, 136, 155, 20 0.125, 0x0050c216afcc, 1, 3, 0, 57, 0, 0, 0x00000995, 226, 58, 113, 20 0.187, 0x0050c216af90, 1, 3, 0, 55, 0, 0, 0x000008a3, 99, 1, 124, 20 0.
PLUS System Manual 4.7 Location Software Library 97 C# Sample Application Overview The C# sample application included in the PLUS software install package is intended to demonstrate how to use the PLUS Location Software Library in a tracking application. 4.7.1 Operating the Sample Application Figure 4-2: C# Sample Application Screenshot The buttons on the form are arranged, from top to bottom, in the order they are commonly used.
Location Software Library PLUS System Manual This calls the ResetBtn_Click() handler, which sets the application to an initialized, empty state. The last-used configuration file is loaded, if one is recorded in the system registry. Once initialization is complete, the code waits for the user to select a data source before continuing. To enable logging position updates to a .
PLUS System Manual Location Software Library 99 public void printMessage(String msg) Displays the string at the bottom of the main window. private void ResetBtn_Click(object sender, EventArgs e) Sets the software to an initialized, empty state and (re)loads the configuration file. private void ConfigBtn_Click(object sender, EventArgs e) Displays a File Open dialog for the user to select a PLUS Location Software Library configuration file.
Visualizer PLUS System Manual 5. PLUS Visualizer 5.1 Overview The PLUS Visualizer application is delivered with the PLUS Location Software Installation. It can be used to quickly setup and deploy a system, and to determine / diagnose problems.
PLUS System Manual Visualizer 101 List View Using the List View, you can see the current status of the PLUS Tags and Readers. Message View Using the Message View, you can see the message traffic from the PLUS Location Software Library, including Time Difference of Arrival (TDOA) calculation messages, and Time Of Arrival (TOA) messages received from the Readers, and the messages output by the location engine as it updates its internal databases.
Visualizer 5.2 PLUS System Manual Menu Bar Figure 5-3: Menu Bar Use the Menu Bar menu to quickly access: 1) File commands to open and save a configuration folder and control logging of system data. 2) View commands to customize the view in the 2D Map View Frame, and select the message types output in the Message Frame. The View menu also enables you to open various statistic windows.
PLUS System Manual Visualizer 103 File Menu Items: Open Config… – identify an existing configuration folder. A configuration folder contains two configuration files, visualizerconfig.txt and trackerconfig.
Visualizer 5.2.2 PLUS System Manual View Figure 5-6: View Menu Use the View menu to: 1) Turn on/off the display of the Toolbar and/or the Status Bar 2) 2D Map View: o Turn on/off the graphical display of the Readers o o o Turn on/off the graphical display of the Tags Turn on/off the graphical display of the background image of the current map.
PLUS System Manual Visualizer 105 Background Image – Show/hide the background image in the 2D Map View. Display Trails – Display a ―breadcrumb‖ history of Tag locations Trail Type – Select either nodes or lines as the display type for the Tag trails Set Trail Length… – Set the desired length for the trail display. Maximum trail length is 1024. Figure 5-7: Set Trail Length Dialog Trail history and position statistics are calculated from the same data.
Visualizer PLUS System Manual Show TDOA Messages – Display, in the Message View Frame, the TDOA messages output by the PLUS location engine TDOA Stats – Display the TDOA Statistics dialog. You can use this dialog to view statistical data about the TDOA messages received for each unique Reader pair, including the number received, average, standard deviation, maximum and minimum TDOA value, and peak-to-peak values. Note the statistics can be sorted by clicking the column header on which to sort.
PLUS System Manual o o o o o Visualizer 107 Max (ns) – Maximum TDOA value received for the given Reader pair Min (ns) – Minimum TDOA value received for the given Reader pair Peak-Peak (ns) –Value of the maximum peak value minus the minimum peak value for the last TDOA message received for the given Reader pair Max Peak-Peak (ns) –Value of the maximum peak-to-peak value received in the last TDOA message received for the given Reader pair Max Std Dev – Maximum standard deviation of the TDOA values receive
Visualizer PLUS System Manual These statistics are computed using the last number of Tag packets (Received Packets) received from the selected Tag. o o o o o o o o o Reader – Name of Reader for which the statistics apply IP Address/ID – MAC address of the Reader Status – Operational status of the Reader—COMMS DOWN or operational. A Reader is marked as COMMS DOWN if a packet has not been received within a given timeout. The timeout is set using the Menu Bar / Settings / Timeouts… submenu item.
PLUS System Manual Visualizer 109 Position Statistics o Reset Stats – Select this button to reset the position statistics for the selected Tag Statistics by Tag The following is a list of the statistical fields and their meaning: The “Num Positions” column indicates the number of data points used for the display statistics.
Visualizer PLUS System Manual When an alarm condition arises, you MUST investigate and resolve the problem. Once resolved, manually clear the alarm using the “Clear selected” or “Clear all” buttons. See Sections 2.7 Troubleshooting Reader Communications and 5.9 Troubleshooting the Visualizer for more information.
PLUS System Manual Visualizer 111 2) Specify 2D view parameters, including the units for display (meters or feet) and parameters for the display of Tag and Readers.
Visualizer PLUS System Manual Figure 5-14: 2D MapView Settings Set Data Input… – specify the source of the Reader data. Figure 5-15: Set Data Input Dialog o o IP Address – Select the IP Address radio button to specify that TOA messages will be received via the network and, using the dropdown list of available IP addresses, select the connection on which to receive the data. Selecting the 0.0.0.0 IP address causes the application to listen on all available network interfaces.
PLUS System Manual Visualizer 113 location engine algorithm. Figure 5-16: PLUS Location Software Library Algorithm Filter Settings o Speed limit – Enter the speed limit of the Tags for use in the Speed Limit filter. The default value is 1.5 meters/second which is normal walking speed. Enter 0 to disable the Speed Limit filter. o Moving average – Enter the depth for use in the Averaging filter Enter 0 to disable the Averaging filter.
Visualizer o PLUS System Manual Rename a Tag You can use this functionality to customize a naming convention. For example, you can name all Tags tracking infusion pumps with the same prefix to enable easy recognition of what resource a Tag represents. o Change the display symbol associated with a given Tag Figure 5-17: Configure Tags Dialog Reader Configuration – display the Configure Readers dialog from which you can interactively configure single or multiple Readers.
PLUS System Manual Visualizer 115 Group Configuration – display the Configure Groups dialog from which you can interactively configure groups. Using this form, you can: o Select a group to configure o Create a new group o Delete a group. Group 0 cannot be deleted. Readers in the group will be moved to group 0 if they are not members of any other groups. o Select the map of which the current group is a member.
Visualizer PLUS System Manual Group/Solver Parameters o Group is in map – Select the map in which this group is located. o Allowed solution types – Enable/disable 0D (presence detect), 1D (linear), and 2D solutions for this group. Enabling 0D enables Presence Detect mode, in which a Tag whose position cannot be determined is assigned to the location of the Reader with the strongest received signal from that Tag. The Tag’s name is listed under the Reader’s name.
PLUS System Manual Visualizer 117 Figure 5-20: Configure Maps Dialog Background Image o Select and scale an image file (bitmap, JPEG, PNG, GIF, TIF) for use as a background image for this map. Member Groups o Move groups in and out of the map. Groups may be members of only one map at a time. Tracking Cell o Clear – Resets the tracking cell to an empty state. o Enter Polygon – Starts a new tracking cell which is entered graphically by clicking on the tracking cell vertices in the Tracking View.
Visualizer 5.2.4 PLUS System Manual Help Figure 5-21: Help Menu Use the Help menu to: 1) View the About Box showing the version information of the PLUS Visualizer software Help Form Fields: About… – display version information about the PLUS Visualizer executable OK – Select the OK button to close the About form Figure 5-22: About Box Dialog Proprietary Information: Do not disclose unless authorized under a Nondisclosure Agreement and the Partner Agreement.
PLUS System Manual 5.
Visualizer PLUS System Manual 1) Specify the number of seconds to collect data to use in determining the calibration value Enter a minimum of 10 seconds – 30 to 50 seconds is recommended. Maximum is 60 seconds. 2) If desired, specify Reader-Cal Tag Associations with the Include/Exclude Reader-Cal Tag Pairs dialog. Select the Set tag-reader associations… menu item in the Calibration window to display it. 3) Use the pull-down lists for Readers and Tags to add combinations to the list.
PLUS System Manual Visualizer 121 4) Select the Start button in the Calibration dialog. A progress bar will denote the status of the calibration process. If you wish to stop calibration before it is complete, select the Stop button. 5) Review the results of the calibration. Select OK to apply the new results if they are satisfactory. Translate – Select this button to dynamically rotate and/or translate the Reader coordinate system into the coordinate system of the graphical display.
Visualizer PLUS System Manual The IP Address column will be 0.0.0.0 for Readers whose IP addresses are not known, or when a logfile is being played back. Reader Stats – Select this button to display the Reader Stats dialog. See Figure 5-11: Reader Stats Dialog for more information about this dialog. If a Reader alarm condition occurs such as it has lost synchronization with the SDP, the Reader Stats button flashes, alerting you to display the Reader Stats and resolve the problem. See Section 5.
PLUS System Manual 5.4 Visualizer 123 Status Bar Figure 5-28: Status Bar Command description Tag summary statistics Use the Status menu to: 1) View command descriptions 2) View Tag summary statistics, including a total Tag count, and the number of Tags positioning, active, and with a comms down status. Proprietary Information: Do not disclose unless authorized under a Nondisclosure Agreement and the Partner Agreement.
Visualizer 5.
PLUS System Manual Visualizer 125 You can customize the 2D Map View Frame display by selecting what you want to display from the Menu Bar / View submenu. See Section 5.2.2 View above. 2D Map View Fields: Double click a Reader icon to display the Configure Readers dialog, with the selected Reader highlighted. See Section 5.2.3 Settings for more information about this dialog. Double click a Tag icon to display the Configure Tags dialog, with the selected Tag highlighted. See Section 5.2.
Visualizer 5.6 PLUS System Manual List View Frame Figure 5-30: List View Frame Use the List View Frame to: 1) View a tabular list of Tags and the their status 2) View a tabular list of Readers and their status 3) Change the name and icon properties of a selected Tag 4) Change the name and icon properties of a selected Reader 5) Configure the Readers 6) Configure the Tags You can customize the List View display by selecting what you want to display using the Toolbar buttons “Tags” and “Readers”.
PLUS System Manual o Visualizer 127 Center View on Reader – Centers the 2D Map View on the Reader to assist in visually finding the Reader on the display. Figure 5-31: Reader List View Menu If the list contains Tag data: a) Double click the line with the desired Tag, or right mouse click the line with the desired Tag and select Configure Tag…, to invoke the Configure Tags dialog discussed in Section 5.2.3 Settings.
Visualizer 5.
PLUS System Manual 5.8 Visualizer 129 Logfile Formats 5.8.1 Position Data The Position Data is logged to the file specified via the Menu Bar / File / Logging… submenu item. See Section 5.2 Menu Bar. 5.8.1.1 Position Data Record Position data records are the timestamped Tag positions as computed by the PLUS location engine.
Visualizer PLUS System Manual also Section 2.7 Troubleshooting Reader Communications for trouble shooting tips for Readers. Tag positions not being graphically updated Tags are dynamically added to the database whenever a Reader receives a message from an ―unknown‖ Tag. If the Tag is in the database, it will be listed in the List View Frame.
