------------------------------------------------------------------------------ CSVSpec.txt v0.5 01 August 2004 ------------------------------------------------------------------------------ Copyright 2004 Don Starr This file may be freely copied and/or distributed, as long as it remains intact and unaltered. The file format specification contained in this document may be implemented by any software, without restriction. Revision history: 0.5 dstarr 2004.08.02 - Removed the PRO-92 -specific MULTO setting. We can use the TT,,, setting instead. 0.4 dstarr 2004.08.01 - Removed the PRO-93/95 -specific M8M setting, because it's the same as: TTM,36,{normal splinter} Reformatted 'details' section. 0.3 dstarr 2004.07.31 - Changed the frequency data in the MULTO line from kHz to Hz, to be consistent with other frequency parameters 0.2 dstarr 2004.07.29 - Filled in descriptions of TT and TTE lines. Added Channel low/high values for the TTE line. Added M8M and MULTO lines, for PRO-92, 93, and 95 Motorola settings 0.1 dstarr 2004.07.12 - Initial version ------------------------------------------------------------------------------ This text file defines the "Extended CSV" format used by Don Starr's WinXX applications. The format is intended to allow the import/export of all system settings from those applications. As of this writing, only Win96 and Win99 support the new format. Win92, Win93, and Win95 will be modified to support it in the near future. All future WinXX apps will use this new format. Once all existing WinXX apps support the new format, support for the WinXXDataConverter program will cease. This CSV format specifies only "data" settings. It does not specify "user" settings. The former includes such things as frequencies, talk group IDs, etc., while the latter might include such user preferences as delay, lockout, and the like. ------------------------------------------------------------------------------ A CSV file consists of lines of plain text, where each line is separated from the others by a carriage-return / line-feed (CRLF) pair. That is, lines of text are delimited by the byte values 0x0D 0x0A. *nix-style newlines (0x0A) are supported, as well. In fact, only the 0x0A is parsed - the 0x0D character is treated as an insignificant whitespace and is always ignored. Each line in the file contains one or more "fields". Multiple fields are delimited by the "comma" character (,). If a field contains a comma character, it must be surrounded by double-quote characters ("). If a field contains double-quote characters, those embedded double-quotes are preceded by another double-quote (i.e. "" represents a single double- quote character in the field). Therefore: abcd,1234 is interpreted as two fields: abcd and 1234 "abcd,1234" is interpreted as one field: abcd,1234 "abcd""1234" is interpreted as one field: abcd"1234 Lines that do not begin with either a Bn field or one of the "valid" data-type codes below will be ignored. This means that the file may contain the following types of lines with no ill effect: * Blank lines - lines that contain nothing but whitespace * Comment lines - lines that begin with a pount (#) character * Lines that contain arbitrary text, as long as that text does not start with either a Bn field or one of the "valid" data-type fields. Whitespace characters (0x20,TAB,LF,FF,etc.) are not significant outside the double-quote delimiters. Therefore, if a field contains significant space characters (0x20), it must enclose the entire field in double-quotes. For example: ,"abcd ", and ,abcd , represent two different things. The former is interpreted as the 4 characters abcd followed by 3 space characters, while the latter is interpreted as ONLY the 4 characters abcd. The newline (0x0A) char is _always_ interpreted, whether or not it is enclosed in quotes. It is therefore an error to embed a newline inside quotes. The only whitespace character that will be "kept" is the space (0x20) char, and then only if it is enclosed in double-quotes. In the text that follows, the following conventions are used: indicates a required field/value [value] indicates an optional field/value {space-delimited list} indicates a value which must be one of the values in the space-delimited list ------------------------------------------------------------------------------ Each line in the WinXX Extended CSV file has the format: [Bn,]<,p1><,p2> ... <,pn> The first field specifies the bank number to which the line applies. Bank numbers start at zero. For example, on the PRO-96, valid bank number values are 0, 1, 2, ... , 9. If this field is not present (i.e. the line starts with the "second" code below), the line's settings are applied to either: a) if a "Bn" field has already been encountered in the CSV file, that bank number is used. Note that this means that for each bank in the file, only one "leading" line need contain the "Bn" field - all subsequent lines for that same bank can start with the "code" value below. b) if no "Bn" field has yet been encountered in the CSV file, then the _current_ bank is the target - this is the bank that is currently displayed on the WinXX "Channels" page. The second field is a code that indicates the contents of the line. Valid codes are: CLR - Clears all bank settings, including trunking modes, channels, talk group IDs, etc. This tag is intended for use at the beginning of a bank's data, so that the bank is as if the scanner had just been "initialized". If this tag is not used, then data in the CSV file is _merged_ with the bank's existing data (if any). CH - A channel entry. This line will contain frequency, etc. for the specified channel TM - Trunking mode. This specifies the trunking mode of the bank. TT - Trunking table - "standard". This specifies a base/offset/step setting for Motorola systems TTE - Trunking table - "extended". This specifies one of several table entries for Motorola systems. TTM - Trunking table "mode". This specifies which "mode" will be used by the scanner for Motorola systems (e.g. normal, splinter, table, etc.). FM - Fleet map. Used in trunked banks, this line will contain the fleet map used by the trunked system. TG - A talk group entry. This line will contain talk group ID, etc. for the specified talk group "slot" in the target scanner. BT - Bank Alpha Tag The remaining fields ( through ) are parameters to each of the above codes, and will vary depending on the code specified. Parameters can be "empty" (i.e. two consecutive comma characters) or omitted entirely. If one parameter is omitted, then the remaining parameters must be omitted, as well (that is, parameters may not be "shifted" to the left - if a parameter is to be omitted but later parameters are to be used, the "missing" parameter must be specified as "empty" - two consecutive comma characters). Empty or omitted params are assigned default values appropriate for the parameter. For example, if the following line appeared in the CSV file: B0,CH,0,,28000000,FM it would mean: Bank 0 Channel entry Channel # = 0 Alpha tag is "empty" = (filled with space characters) Frequency = 28000000 Hz (28.000000 MHz) Rx Mode = FM CTCSS tone frequency is "omitted" = 0 Hz Car # is "omitted" = (none assigned) ============================================================================== Detailed Code List ============================================================================== CLR - Clears the bank, removing all channel, trunking, and other settings. The bank's state is as if the scanner had been "initialized". Format: CLR (no parameters) ----------------------------------------------------------------------------- CH - Assigns frequency data, etc. to a channel entry Format: CH,,,,,, Channel Zero-based channel number appropriate for the target scanner DEFAULT: 0 AlphaTag Alpha-numeric (plus whatever ASCII codes the target scanner recognizes). Must "fit" in the target scanner's alpha tag size; if it's too long, it will be truncated. DEFAULT: space characters to fill scanner's tag size Frequency Channel frequency, in Hz. Must be "valid" for the target scanner's supported frequency ranges; if it's outside those ranges, it will be adjusted to fit. DEFAULT: 0 RxMode {AM FM MO ED LT CT DC} The receive mode for the channel: AM/FM self-explanatory MO Motorola trunked ED EDACS trunked LT LTR trunked CT CTCSS DC DCS DEFAULT: FM If the specified mode is not valid for the target scanner, it will be set to FM. CTCSS/DCS CTCSS tone frequency in Hz, or DCS code If indicates that the channel is CTCSS or DCS, this field specifies the tone frequency or code for the channel. This field is optional. It is ignored in any modes other than CT or DC; if it is not present in a CT or DC channel, the value is set to 0 Hz or 000, respectively. DEFAULT: 0 Hz for a CTCSS tone, 000 for a DCS code EXCEPTION: The PRO-99 does not support varying receive modes for channels - they are always FM. Any non-empty CTCSS/DCS field is always interpreted as a CTCSS frequency. Car Used in the PRO-99 racing scanner, this parameter specifies a car number for the channel. Valid values are 1-, 2-, or 3-character strings of decimal digits from 0 through 999. If empty or omitted, no car number is assigned to the channel. DEFAULT: (no car number assigned) ----------------------------------------------------------------------------- BT - Assigns an alpha tag to the bank Format: BT, AlphaTag Alpha-numeric (plus whatever ASCII codes the target scanner recognizes). Must "fit" in the target scanner's alpha tag size; if it's too long, it will be truncated. DEFAULT: (space characters to fill alpha tag entry) ----------------------------------------------------------------------------- TM - Sets the bank's trunking mode Format: TM, Mode The trunking mode for the bank. Must be one of: na - none (conventional) ED - EDACS MO = Motorola LT = LTR DEFAULT: na ----------------------------------------------------------------------------- TT - Sets the base/offset/step values used by some Motorola trunked systems Format: TT,,, BaseFreq The base frequency, in Hz DEFAULT: 406000000 OffsetChan The offset channel DEFAULT: 380 StepSize The step size, in Hz DEFAULT: 25000 ----------------------------------------------------------------------------- TTE - Programs an "extended table" entry. These are the multiple base/ offset/step settings used by some Motorola trunked systems. For example, the PRO-96 allows you to program up to six of these settings in each bank. Format: TTE,,,,,, Index The zero-based entry index DEFAULT: 0 BaseFreq The base frequency, in Hz DEFAULT: 406000000 OffsetChan The offset channel DEFAULT: 380 StepSize The step size, in Hz DEFAULT: 25000 ChannelLo The starting channel number that uses this entry DEFAULT: 380 ChannelHi The ending channel number that uses this entry DEFAULT: 759 ----------------------------------------------------------------------------- TTM - Sets the trunking table "mode" for Motorola systems Format: TTM,, CCType The type of control channel this setting affects. Must be one of: 36 - 3600 bps CC 96 - 9600 bps CC DEFAULT: 36 Mode The trunking mode. Must be one of: normal - "normal" trunking plan splinter - "splinter" plan for 800 MHz 3600 systems. table - Use the single base/offset/step values set by the TT setting above multi - Use the multiple base/offset/step values set by the TTE setting above DEFAULT: normal ----------------------------------------------------------------------------- FM - Sets the fleet map for Motorola systems Format: FM,,,,,, ,, SizeCodeN The size code for block . Each size code must be either the Motorola- or Uniden-format size code, according to the following table: Motorola Uniden A S1 B S2 C S3 D S4 E S5 F S6 G S7 H S8 I S9 J S10 K S11 M S12 O S13 Q S14 2 or S0 or for "Type-II" blocks For example, the following two lines are equivalent: B1,FM,C,J,D,D,2,,D,D B1,FM,S3,S10,S4,S4,,S0,S4,S4 "Invalid" combinations may have undefined effects. For example, if the following is specified: B1,FM,S3,S10,S4,S4,,S0,S13,S13 the behavior is undefined. This line is invalid because size code 13 occupies 4 blocks, and only two blocks are set to S13 above. ----------------------------------------------------------------------------- TG - Sets a talk group entry Format: TG,,,, SubBank Specifies the sub-bank for the talk group ID. For example, on the PRO-96 this parameter can take the values 0 - 4. DEFAULT: 0 Index Talk Group entry number The index of this entry in the specified sub-bank. For example, on the PRO-96 this parameter can take the values 0 - 29. DEFAULT: 0 NOTE: The parameter is provided so that IDs may be "partitioned" into logical groups. The PRO-93, 95, and 96 scanners support this feature natively. However, the PRO-92 does not - it merely allows 100 Talk Group IDs in each bank. Win92 handles this as follows: Writing: The 100 IDs are divided into 5 "subbanks" of 20 IDs each. This results in the range 0-00 through 4-19, like the PRO-93 and 95 Reading: Each is assumed to contain 20 IDs. If is greater than 4, is greater than 19, or x 20 + is greater than 99, the entry is ignored. AlphaTag Alpha-numeric (plus whatever ASCII codes the target scanner recognizes). Must "fit" in the target scanner's alpha tag size; if it's too long, it will be truncated. DEFAULT: (space characters to fill alpha tag entry) ID A talk group ID valid for the current bank trunking mode, specified in a format appropriate for the bank's trunking mode and fleet map: Motorola, Type-II Decimal Mot, Type-I or I/II Decimal, BFF-SS, or BFFF-S format, depending on Fleet Map EDACS AFS format (AA-FFS) LTR A-HH-UUU format (Area, Home repeater, User) DEFAULT: 0 NOTE: The bank's Trunking Mode and Fleet Map must be set _before_ the Talk Group entries, so that a program will know how to interpret the field. ============================================================================== Examples: The following block of data configures a PRO-96 Bank 1 for the Motorola Type-II system used by the City of Santa Clara, CA. In addition, it adds three conventional (non-trunked) frequencies. One of those frequencies is out of the PRO-96's "normal" range. Because of this, the "Extended Frequencies" box on Win96's "Settings" page must be checked before importing this data. B1,CLR B1,BT,"Santa Clara" B1,TM,MO B1,TTM,36,normal B1,FM,S0,S0,S0,S0,S0,S0,S0,S0 B1,CH,0,SantaClaraC1,867862500,MO B1,CH,1,SantaClaraC2,868625000,MO B1,CH,2,SantaClaraC3,868887500,MO B1,CH,3,SantaClaraC4,866200000,MO B1,CH,4,SantaClaraC5,866262500,MO B1,CH,5,SantaClaraC6,866462500,MO B1,CH,6,SantaClaraC7,866837500,MO B1,CH,7,SantaClaraC8,866912500,MO B1,CH,8,SantaClaraC9,867075000,MO B1,CH,9,SantaClaraCA,867337500,MO B1,CH,10,SantaClaraCB,868987500,MO B1,CH,11,"CHP Base",42500000,CT,131.8 B1,CH,12,"CHP Cars",42280000,CT,131.8 B1,CH,13,WWV,25000000,AM B1,TG,0,0,"Police Disp",16 B1,TG,0,1,"Police Incid",48 B1,TG,0,2,"Police Dets",80 B1,TG,0,3,"Police Recs",112 B1,TG,0,4,"Citywd Emerg",144 B1,TG,0,5,"Fire Disptch",272 B1,TG,0,6,"Fire Incid 1",304 B1,TG,0,7,"Fire Incid 2",336 B1,TG,0,8,"Fire Incid 3",368 Some notes on this sample data: * The lines for channels 0 through 10 use the "default" value for the CTCSS/DCS field - because these are Motorola channels and the CTCSS/DCS field is meaningless. * The "Car" field is omitted from all channel entries. The PRO-96 does not support Car data. * The "B1" field is only really necessary on the first line (B1,CLR), as subsequent lines that don't have that field will use the last-encountered bank number (in this case, bank 1). * The FM (fleet map) field could've been specified as: B1,FM (i.e. no size codes), as the default value for those parameters is zero. * No "Trunking Table" (TT) or "Trunking Table Extended" (TTE) lines are present, as the system uses the "default" values (and the TTM line is set to "normal").