Last modified 6 years ago Last modified on 05/14/11 12:43:03

P25-in-UDP Encapsulation

The P25-in-UDP encapsulation is known as P25CAI. THIS allows frames conforming to the P25 common air interface (CAI) to be passed inside UDP datagrams. This allows for BOTH 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 provides meta-information for 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 radiotap header which is widely used to describe IEEE 802.11 traffic; and also on the gsmtap header which is used by Airprobe to describe GSM traffic. The minimum information contained by this header is described as follows:

struct p25cai_hdr {
  uint8_t version;  /* 0 at present. */
  uint8_t pad;
  uint16_t length;  /* length of the header */
  uint32_t seq_no;  /* frame sequence number */
  uint32_t present; /* bit-mask indicating which optional fields are present */
} __attribute__((packed))

The header contains both mandatory and optional fields and numbers are all in network byte order. The optional fields are, if present, specified by setting the appropriate bit in the "present" bitmask. These fields are listed in order of bit number:

Bit number Field
0 Timestamp (in ms)?
1 Frequency (in kHz)?
2 Logical channel?
3 RSSI/TX power (in dBm)?
31 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 optional 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.

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 p25lib library provides support for manipulating the encapsulation header and P25 CAI frames. A simple stand-alone parser and formatter in C/C++ is provided as well as code for handling CAI data units. We are re-factoring the OP25 codebase so that GNURadio is used for the signal processing and p25lib for all higher-level frame handling. Until the official release of p25lib we'll give the formatter/parser as attachments to this page.

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