Reference / Paper · 2017
Whistler Remote Control Protocol, CC Dump Protocol & Audio File Header Format v1.7 (WS1080/WS1088, WS1095/WS1098, TRX-1, TRX-2)
- scanner
- whistler
- remote control
- protocol
- serial
Reference / Paper · 2017
WS-1080/WS-1088 EZ Scan Digital Handheld Scanner WS-1095/WS-1098 EZ Scan Digital Base/Mobile Scanner TRX-1 Digital Handheld Scanner TRX-2 Digital Base/Mobile Scanner Remote Control Protocol CC Dump Protocol Audio File Header Format Version 1.7 – August 1, 2017 This document is intended for use by experienced software developers and is subject to the following disclaimer: Whistler Group, Inc., provides the Remote Control Protocol, Clock Set Protocol, CCDump Protocol and Audio File Header Specifications (the "Specifications") AS IS for the convenience of scanning hobbyists and programmers who wish to develop software applications for use with the Whistler Scanners listed above. Use of the Specifications shall be AT YOUR OWN RISK. Whistler Group does not provide technical support for these protocols. Should you require assistance with the Specifications, we encourage you to visit one of the many Whistler User Group forums on the Internet. By using the Specifications, you agree to these terms. Whistler Group Digital Scanner Remote Control Protocol, CC Dump Protocol and Audio File Header Format Whistler Digital scanners include a simple remote control interface protocol (RCIP) that is suitable for use with a PC application designed to provide a remote control and display capability. The ideal application should provide a means by which a user can interact with a visual representation of the scannerʼs keypad and display. As of firmware released in June of 2017 for the WS-1080, WS-1088, WS-1095, WS1098, TRX-1, and TRX-2, it is also an option to get information about the currently active channel. Remote Control Mode is active at all times, and does not require that the radio be placed in any special remote mode in order for it to be used. The basic remote control command/response format is as follows: <STX><msgCode><msgData><ETX><sum> where: <STX> An ASCII “Start of Text” symbol (0x02) <msgCode> A single character code that represents the command or response message type. Please be aware that this code is case sensitive (i.e. T and t are not the same) <msgData> The data that accompanies a command or a response. Not all requests require this item. The length and format of this data depends on the type of request being made. <ETX> An ASCII “End of Text” symbol (0x03) <sum> An unsigned char type sum of all bytes starting with <msgCode> up to and including <ETX> anded with the value 0xFF. This value must be calculated and sent with every command and response for error checking. Version 1.7 – August 1, 2017 Page 1 Whistler Group Digital Scanner Remote Control Protocol, CC Dump Protocol and Audio File Header Format The following commands are supported in the Remote Control protocol: Get Status Command: STX A ETX <sum> Response: STX A <mode> <sq> <battL> <battH> <rssiL> <rssiH> <zmL> <zmH> <ledR> <ledG> <ledB> <freq0> <freq1> <freq2> <freq3> <rxmode> ETX <sum> sq: bit 0: RF Squelch state bit 1: Unmuted state bit 2: /XF state (IMBE detect) battL: battH: rssiL: rssiH: zmL: zmH: ledR: ledG: ledB: freq: rxmode: Low byte of batt level High byte of batt level (OR 0x80 if USB) Low byte of RSSI value High byte of RSSI value Low Byte of ZeroMatic value High byte of ZeroMatic value Red LED intensity (0-255) Green LED intensity (0-255) Blue LED intensity (0-255) Current frequency, little-endian 0=AM, 1=FM, 2=NFM <mode> values (Values are in HEX): 00 Main Menu 0B Weather 01 Browse Objects 0C Skywarn 02 Browse Library 0D Weather Menu 03 Location Select 0E Sweeper Menu 04 Scanlist Edit 0F Service Search Menu 05 Scanlist Set Edit 10 Search Lockouts Menu 06 Top Search Menu 11 Sweeper 07 Select Config 12 Search 08 Update from Library 13 Search settings Menu 09 Monitor Object 14 Sweeper Settings Menu 0A Scan Get LCD Version 1.7 – August 1, 2017 Page 2 Whistler Group Digital Scanner Remote Control Protocol, CC Dump Protocol and Audio File Header Format Command: STX L ETX <sum> Response: STX L <lcd0> <lcd1> ... <lcd96><icons1><icons2><icons3>ETX<sum> <lcd0> through <lcd96> are the characters found on the scanner’s display (6 lines at 16 characters per line). NOTE: Not all characters displayed on the scanner’s LCD display are available on the screen data. Items such as check boxes and cursor arrows are not available in the data provided using this command. <icons1>, <icons2> and <icons3> are bitmapped representations of display icon status, as follows: icons1: bits 0-2: bit 3: bit 4: bit 5: bit 6: RSSI bars level, 0-5 S icon Batt icon ON Batt icon BLINKING Ext Power Icon icons2: bit 0: bit 1: bit 2: bit 3: bit 4: bit 5: bit 6: bit 7: Fn icon 'G' icon 'A' icon 'T' icon Unused Unused Play Icon Pause Icon icons3: bits 0-2: bit 3: bit 4: bit 5: bit 6: bit 7: Signal Type 'IF' icon Trunk2 icon PRI icon TrunkS icon Unused Version 1.7 – August 1, 2017 Page 3 Whistler Group Digital Scanner Remote Control Protocol, CC Dump Protocol and Audio File Header Format Signal Types: 0: Off 1: DG 2: Dg 3: AM 4: FM 5: NFM 6: ENC 7: D2 Get Active Channel Information Command: STX a ETX <sum> Response: STX a <lenH> <lenL> <data> ETX <sum> Where: <lenH> = High byte of the length of the response data <lenL> = Low byte of the length of the response data <data> = <len> bytes of data. If the scanner is actively monitoring a transmission, <len> will be the size of the recording header defined later in this document followed by the contents of that recording header data. If there is currently no transmission in progress, <len> will be set to 0 and <data> will be empty (Total length 6 bytes). Note: The channel does not have to have the recording flag set in order to use this command. Notes regarding the fields in the recording header: 1. All numeric fields are in big-endian format and will need to be converted for use on a PC. 2. The Talkgroup ID #2 field will contain the radio ID that initiated the call if available throughout the transmission 3. The Radio ID #1 field will be updated in real time Version 1.7 – August 1, 2017 Page 4 Whistler Group Digital Scanner Remote Control Protocol, CC Dump Protocol and Audio File Header Format with the current available radio ID value. 4. If no radio ID is available for either of the above fields, the value of 0xFFFFFFFF will be returned. 5. The Info alpha tag field will contain the Talkgroup ID in the format shown on the scanner’s display. 6. This command requires firmware released in June 2017 or later. Send Key Command: STX K <keycode> ETX <sum> Response: (no response) Key codes for the Send Key command are as follows: Key Code Key Code MENU SKIP ATT 17 1 15 8 16 12 29 30 31 32 33 40 43 PLAY/SEL/PAUSE WX 9 3 10 2 5 19 22 23 24 25 26 41 44 Fn 1 3 5 7 9 Knob CW Knob push PRI . (decimal) 2 4 6 8 0 Knob CCW POWER Note: CPU Firmware version 1.2 or higher is required for use with this command. Earlier versions of the firmware do not handle this command correctly. Clock Set Version 1.7 – August 1, 2017 Page 5 Whistler Group Digital Scanner Remote Control Protocol, CC Dump Protocol and Audio File Header Format Command: STX t <sec> <min> <hour> <mday> <month> <year> <weekday> <yearday> <isDST> ETX SUM Note: All parameters for this command are 16 bit short integers as follows: sec: min: hour: mday: month: year: weekday: yearday: isDST: Seconds after the minute [0-59] Minutes after the hour [0-59] Hours since midnight [0-23] Day of the month [0-31] Months since January [0-11] Years since 1900 Days since Sunday [0-6] Days since January 1 [0-365]* Time is Daylight Saving Time* Items marked with an asterisk (*) are optional and may be set to a value of 0. Response: (no response) Power Status Request Command: STX P ETX <sum> Response: STX P <status> ETX <sum> Status indicates the current power state of the scanner as follows: 0: 1: Scanner is Off Scanner is On Version Request Version 1.7 – August 1, 2017 Page 6 Whistler Group Digital Scanner Remote Control Protocol, CC Dump Protocol and Audio File Header Format Command: STX 'V' 0x00 ETX <sum> Response: STX 'V' 0x00 <mod1> <mod2> <mod3> <mod4> <mod5> <mod6> <mod7> <mod8> <bb> <cc> <dd1> <dd2> ETX <sum> <mod1> through <mod8> are ASCII characters of the model number identifier string. In the case of the WS1080, this model number is “WS1080 “. <bb> <cc> <dd1> <dd2> Boot version CPU version DSP version 1 DSP version 2 These values contain the major version in the 4 high bits, and the minor version in the 4 low bits. CCDump Control Command: STX C <value> ETX <sum> Response: (no response) <value> determines if the CC Dump function to the USB Serial port should be turned on or off and may have the following values: 0: 1: Turn the CC Dump off Turn the CC Dump On Note: Use of this command will set the CC Dump value in the scanner’s configuration data. If the CC Dump to SD Card option was enabled before using this function, it will be automatically disabled. Manual intervention will be required to re-enable the CC Dump to file option. Version 1.7 – August 1, 2017 Page 7 Whistler Group Digital Scanner Remote Control Protocol, CC Dump Protocol and Audio File Header Format Control channel data dump format Whistler scanners feature a trunked control channel decoding function called CCDump. When CCDump is turned on, the scanner sends decoded trunking control channel information and SAME weather alert data to the PC/IF port or to a file on the scanner’s internal Micro SD card. This data can be displayed using any simple terminal application, or, read by third party application software for additional analysis and decoding. CCDump is turned off by default in the scanner. To activate CCDump, press the MENU key, then scroll down to the SETTINGS menu and press SEL to enter the settings menu. In the Settings menu, scroll down to the PC/IF CCDump option. Press the SEL key to toggle the option on or off. Once the option is set, press the MENU key and then the SEL key to accept the changes. To view CCDump data, connect the radio to a personal computer using the USB PC/IF cable. Start a terminal program or your third party application software. Configure the communications parameters for “115200, N, 8, 1” as follows: COM Port: The COM port number assigned to the scanner by your computer. If you are running a Windows operating system, you can find this information under “Ports” in the Device Manager. Parity: None Baud Rate: 115,000 bits per second Word: 8 bits Stop Bits: 1 Basic CCDump data includes the system type, the Object ID of the TSYS object (if applicable), and the “raw” control channel messages as they are transmitted by the system. This data is delimited by “:” symbols. Basic CCDump data is sent to the PC/IF port when the radio is monitoring a trunked control channel while in PAUSE or SCAN modes. Version 1.7 – August 1, 2017 Page 8 Whistler Group Digital Scanner Remote Control Protocol, CC Dump Protocol and Audio File Header Format CC Dump Message Format The following describes the CCDump message format when used on trunked radio systems: <Type>:T<xxxxxxxx>[:S<yyyy>][:CC<zz>][:<SubType>]:<CC Data>[:<Decode Data>] <Type>: One of the following three ASCII character combinations: P25: Project 25 control channel or voice channel data MOT: Motorola 3600 control channel data LTR: LTR low speed data ED : EDACS control channel data (both Wide and Narrow) <xxxxxxxx>: The hexadecimal representation of the TSYS's File System ID (for WXS and WXT, this is the current WX Chan 0000-0006) <yyyy>: The site number within the current TSYS data. For P25 Conventional voice, this will be “0000”. This field is not present when the <Type> field is WXS or WXT. <zz>: The control channel within the site being decoded. This field is not present when the <Type> field is WXS or WXT. <SubType>: The P25 packet subtype. This is only used and present when the <Type> is set to P25. <CC data>: The "osw" from the CC. The format depends on the system type. <Decode Data>: If present, how the scanner decoded the data. Version 1.7 – August 1, 2017 Page 9 Whistler Group Digital Scanner Remote Control Protocol, CC Dump Protocol and Audio File Header Format CC Data Formats: P25: The format of P25 data depends on the SubType field. Each SubType field is listed below. P25TSBK: This data sub type contains basic control channel messages in the following format: <X1><X2><X3><X4><X5><X6><X7><X8><X9><XA><XB><XC> where <X1> - <XC> are 12 2-digit hexadecimal bytes from the last message received. Each item is separated by a space character. P25ES: This data sub type contains encryption sync control messages transmitted on the voice channel. These messages have the following format: <X1><X2><X3><X4><X5><X6><X7><X8><X9><XA><XB><XC> where <X1> - <XC> are 12 2-digit hexadecimal bytes from the last message received. Each item is separated by a space character. P25LC: This data Sub Type contains link control messages transmitted on the voice channel. These messages have the following format: <X1><X2><X3><X4><X5><X6><X7><X8><X9> where <X1> - <X9> are 9 2-digit hexadecimal bytes from the last message received. Each item is separated by a space character. LCTG: This data sub type contains the talkgroups advertised on a link control message. P25HDU: This data Sub Type contains the Header Data Unit control messages transmitted on the voice channel. These messages have the following format: <X1><X2><X3><X4><X5><X6><X7><X8><X9><XA><XB><XC><XD><XE> where <X1> - <XE> are 15 2-digit hexadecimal bytes from the last message received. Each item is separated by a space character. P25PDU: This data sub type contains extended control channel data messages. These are messages that do not fit into a standard P25TSBK data type. These messages have the following format: <Position>/<Total> : <X1> : <X2> : <X3> : <X4> : <X5> : <X6> : <X7> : <X8> : <X9> : <XA> : <XB> : <XC>. <Position>: Packet number of the sequence of data packets being transmitted within the extended data. <Total>: Total number of packets being transmitted in this extended data packet. <X1> - <XC>: The actual data being sent as 12 2 byte hexadecimal bytes. Each item is separated by a colon (:). Version 1.7 – August 1, 2017 Page 10 Whistler Group Digital Scanner Remote Control Protocol, CC Dump Protocol and Audio File Header Format MOT: This type indicates a Motorola system and has the following format from the control channel: <cmd> <dir> <id> <cmd>: <dir>: <id>: 3-digit (10-bit) hex "command" value direction bit 4-digit (16-bit) hex "id" value When Monitoring a P25 CAI voice channel, the P25ES, P25LC and P25HDU P25 SubType fields will be presented to the PC/IF Port and will be in the following format: <SubType>:<Data> <SubType>: The P25 sub type (P25ES, P25LC or P25HDU) <Data>: The data associated with the sub type. See the P25 section for a description of these sub type data formats. When monitoring a non-P25 voice channel on this system type, the scanner will provide the sub-audible data found on the voice channel. Sub-audible data will appear as follows: Sa:<data> <data>: 16 bit hexadecimal value The final sub-audible packet will be in this format: Sa:End:pattern The Motorola end code was detected Sa:End:noise Noise was received that cannot be voice. LTR: This type indicates a received signal on an LTR channel and has the following format: <RR>:<A>-<GG>-<HH>-<III>-<FF> <RR>: <A>: <GG>: <HH>: <III>: <FF>: ED : Repeater on which the msg was received area Goto/In-Use repeater # Home Repeater # Group ID Free Repeater # This type indicates a control channel message from an EDACS system and has the following data format: <W>:<ccc><ppppppp> <W>: <ccc>: Which of the two blocks (0 or 1) in the msg pair this is Command value. Represents a variable # of bits from the received data (since commands are variable length) <payload>: remainder of msg, after removing the <ccc> command value Version 1.7 – August 1, 2017 Page 11 Whistler Group Digital Scanner Remote Control Protocol, CC Dump Protocol and Audio File Header Format CC Dump Conventional Data Message Format The following describes the CCDump message format when used on conventional P25 channels: C<xxxxxxxx>:<SubType>:<Data> <xxxxxxxx>: The hexadecimal representation of the conventional channel's File System ID <SubType>: The P25 packet subtype. Possible sub types are P25ES, P25LC and P25HDU. See the P25 section for a description of these sub types. <Data>: The data associated with the sub type. CC Dump Weather Data Message Format The following describes the CCDump message format when used on weather radio decode: <Type>:T<xxxx>:<Data> <Type>: One of the following three ASCII character combinations: WXS: WX SAME Data WXT: WX 1050Hz tone detection WXS: <xxxx>: A 4 digit representation of the current WX channel the messages was received from. <Data>: The data received. The format depends on the system type. This type indicates that a SAME data message has been received on one of the WX channels and has the following format: ZCZC-<Origin>-<Code>-<Location> <Origin>: The origin of the message. Weather events are usually “WXR”. <Code>: A three letter designation of the type of message being sent. <Location>: A 6 digit location id. More information on the <Code> and <Location> fields may be found at http://www.nws.noaa.gov/nwr/nwrsame.htm. WXT: This type indicates that the scanner is operating the WX Priority mode and has detected a 1050Hz tone on one of the WX frequencies. This message takes the following format: “1050Hz Detect” Version 1.7 – August 1, 2017 Page 12 Whistler Group Digital Scanner Remote Control Protocol, CC Dump Protocol and Audio File Header Format Audio File Header Information The following section describes the header information located at the beginning of the audio files created by the scanner. 320 bytes are reserved at the start of the file to hold this information. This structure is also used for the Get Active Channel Information command. Offset 0 4 8 Data Type unsigned long unsigned long unsigned long Default Value 0x2E736E64 (".snd") 320 0xFFFFFFFF 12 16 20 24 unsigned long unsigned long unsigned long unsigned char 1 8000 1 25 struct stm 43 60 77 94 98 102 106 110 114 131 135 152 156 160 162 164 165 char[17] char[17] char[17] unsigned long unsigned long unsigned long unsigned long unsigned long char[17] unsigned long other[17] unsigned long unsigned long unsigned short unsigned short unsigned char reserved[155] Description Magic Number, standard value for .AU files. Offset to start of audio data. Audio data size, set to 0xffffffff to indicate “unknown”. Use the file size – 320 to get the correct value. Encoding format, always set to 1 (uLaw) Sample rate. Always 8000 samples per second. Channel count (1=Mono) Recording Type. Possible values are: 0: Conventional 1: Talkgroup 2: Search Date and time recording was started. See structure information below for more details. Object alpha tag Trunked system alpha tag (if trunked) Info alpha tag (Miscellaneous information) Object ID Talkgroup ID #1 Talkgroup ID #2 Radio ID #1 Radio ID #2 Site Name (Multi-Site trunked systems only) TSYS File Index Misc text info (e.g. DMR slot and color code) Voice frequency Control channel frequency (if applicable) Squelch mode (0=No Tone,1=CTCSS,2=DCS,3=NAC) Squelch value TSYS Type Reserved for future data The structure information for the recording start time is provided below. All values in this structure are in Little Endian byte order. struct stm { short int tm_sec; short int tm_min; short int tm_hour; short int tm_mday; short int tm_mon; short int tm_year; short int tm_wday; short int tm_yday; short int tm_isdst; }; Version 1.7 – August 1, 2017 //seconds after the minute (from 0) //minutes after the hour (from 0) //hour of the day (from 0) //day of the month (from 1) //month of the year (from 0) //years since 1900 (from 0) //days since Sunday (from 0) //day of the year (from 0) //Daylight Saving Time flag Page 13 Whistler Group Digital Scanner Remote Control Protocol, CC Dump Protocol and Audio File Header Format TSYS Type Values: Value 0 1 2 3 4 5 System Type Motorola EDACS LTR Project 25 (P25) DMR NXDN Notes: 1) All integer values are in Big-Endian format. 2) All frequencies are in Hertz. 3) For CTCSS and DCS, the following tables are used to look up the correct values. For NAC, convert the Squelch value to a three character hexadecimal value. CTCSS: Value 0 4 8 12 16 20 24 28 32 36 40 44 48 Tone 67.0 77.0 88.5 100.0 114.8 131.8 151.4 165.5 177.3 189.9 203.5 225.7 250.3 Value 1 5 9 13 17 21 25 29 33 37 41 45 49 Version 1.7 – August 1, 2017 Tone 69.3 79.7 91.5 103.5 118.8 136.5 156.7 167.9 179.9 192.8 206.5 229.1 254.1 Value 2 6 10 14 18 22 26 30 34 38 42 46 Tone 71.9 82.5 94.8 107.2 123.0 141.3 159.8 171.3 183.5 196.6 210.7 233.6 Value 3 7 11 15 19 23 27 31 35 39 43 47 Tone 74.4 85.4 97.4 110.9 127.3 146.2 162.2 173.8 186.2 199.5 218.1 241.8 Page 14 Whistler Group Digital Scanner Remote Control Protocol, CC Dump Protocol and Audio File Header Format DCS: Value 0 4 8 12 16 20 24 28 32 36 40 44 48 52 56 60 64 68 72 76 80 84 88 92 96 100 104 108 Tone 006 021 031 047 054 073 116 132 145 162 205 225 245 255 266 311 332 356 411 431 452 464 506 532 612 632 703 732 Value 1 5 9 13 17 21 25 29 33 37 41 45 49 53 57 61 65 69 73 77 81 85 89 93 97 101 105 109 Version 1.7 – August 1, 2017 Tone 007 023 032 050 065 074 122 134 152 165 212 226 246 261 271 315 343 364 412 432 454 465 516 546 624 654 712 734 Value 2 6 10 14 18 22 26 30 34 38 42 46 50 54 58 62 66 70 74 78 82 86 90 94 98 102 106 110 Tone 015 025 036 051 071 114 125 141 155 172 214 243 251 263 274 325 346 365 413 445 455 466 523 565 627 662 723 743 Value 3 7 11 15 19 23 27 31 35 39 43 47 51 55 59 63 67 71 75 79 83 87 91 95 99 103 107 111 Tone 017 026 043 053 072 115 131 143 156 174 223 244 252 265 306 331 351 371 423 446 462 503 526 606 631 664 731 754 Page 15 Whistler Group Digital Scanner Remote Control Protocol, CC Dump Protocol and Audio File Header Format Audio File Index File In addition to the audio files created by the scanner, it will also create an index file to indicate what audio files are present on the scanner’s SD Card. File Name: ARINDEX.DAT Location: Rec folder Offset 0 8 Data Type char[8] unsigned long Default Value ARINDEX\0 Array of recordings Description Identification/Verification string An array of unsigned long integers (Little Endian) each indicating an existing recording number. To build the file name that matches the audio file, use the following process. There are a maximum of 200 audio recordings (numbered 000 through 199) in each folder. Each folder is a zero padded 5 character folder (i.e. Folder 1 would be 00001) starting at folder number 0 (00000). To calculate the folder name, use the integer portion of this formula: FolderID = Index/200 The file name is a zero padded 3 character name with a .AU file extension. To calculate the file name from the index, use this formula: FileID = Index%200 Version 1.7 – August 1, 2017 Page 16