OP25j

P25-in-UDP Encapsulation

The P25-in-UDP encapsulation allows frames conforming to the P25 common air interface (CAI) to be passed inside UDP datagrams. This allows for unicast and multicast distribution of P25 CAI message traffic across IP networks. Sending P25 CAI traffic across an IP network may be used to link repeaters via the Internet and allow for traffic analysis and logging services to be implemented using conventional computing equipment.

Every UDP frame contains an encapsulation header and an encapsulated P25 frame: * The encapsulation header describes the P25 frame. * The encapsulated P25 CAI frame is the message as it is sent over the air interface.

=== The P25CAI Encapsulation Header ===
The UDP datagram begins with a short header which is used to describe the P25 CAI frame. The format of the encapsulation header is closely modeled on the [http://www.radiotap.org radiotap] header which is widely used to describe IEEE 802.11 traffic; and also on the [http://bb.osmocom.org/trac/wiki/GSMTAP gsmtap] header which is used by Airprobe to describe GSM traffic. The minimum information contained by this header is described as follows:

{{{
struct p25cai_header {
uint8_t version; /* 0 at present. /
uint8_t pad;
uint16_t length; / length of the header in octets in network order /
uint32_t channel; / logical channel number in network order /
uint32_t present; / bit-mask indicating which optional fields are present in network order */
} attribute((packed))
}}}

The header may contain a number of optional fields which, if present, are specified by setting the appropriate bit in the "present" bitmask. These fields are listed in order of bit number:

	Bit number		Field
	0		[EhSequenceNo Sequence number]
	1		[EhTimestamp Timestamp]
	2		[EhFrequency Frequency]
	3		[EhRssi RSSI]
	31		[EhExtended Extended bitmask]

When an optional field is indicated to be present by the present bitmask then the following rules apply: * Fields are strictly ordered; The developer can specify any combination of fields, but the data must appear following the encapsulation header in the order they are specified in the present bitmask (or more accurately, in the order the bit numbers for the present bitmask are defined). * Field lengths are implicit: the encapsulation header format does not specify field lengths, it is expected that the developer knows the corresponding length based on the data field name. * Variable-length fields are not supported since field lengths are implicit. * Support for extended bitmasks must be implemented, see below. * The field is specified in network byte order and must be converted to host order before use, see below.

==== Field Order ====
All fields are required to use network byte-order. This applies to optional fields and also to mandatory fields including the version, length, channel and present fields in the encapsulation header. This is in contrast to gsmtap and Radiotap but unlike those headers the P25CAI encapsulation is intended for transmission over the network.

==== Field Alignment ====
The encapsulation requires that all fields (whether mandatory or optional) be naturally aligned. All fields in the encapsulation header must be aligned to natural boundaries. That means all 8-, 16-, 32-, and 64-bit fields must begin on 8-, 16-, 32-, and 64-bit boundaries, respectively. In this way, generators and parsers can avoid unaligned accesses to encapsulation header fields. This wiki has adopted the stdint.h convention of using uint64_t, uint32_t and uint16_t to denote 64-, 32- and 16-bit quantities.

==== Extended Bitmasks ====
To allow for future extension parsers extented bitmasks will be used. If bit 31 of the present field is set, an extended present bitmask is present. Radiotap parsers must check for the presence of bit 31 in the present field to identify if a second 32-bit bitmask is present in the encapsulation header. Additional bitmasks may be chained to the end of extended bitmasks by setting bit 31 in each bitmask to indicate a follow-up one. Field bits in an extended bitmask still counted starting from 32, 64, etc. so that field number 63 is also reserved because bit 31 is reserved in every (extended) bitmask.

=== The Encapsulated P25CAI Frame ===
The encapsulated P25 frame immediately follows the encapsulation header. The format of the frame is given by the P25 Common Air Interface standard which specifies the message types, their content and bit ordering.

Project 25 FDMA Common Air Interface Description (TIA-102.BAAA-A),
Telecommunications Industry Association,
2500 Wilson Boulevard, Arlington, VA 22201, USA,
September 2003