POCSAG-GO v2.0.0

Complete Go implementation of POCSAG pager protocol with encoder and decoder, directly ported from pocsag-tool.

Features

• ✅ Full POCSAG encoder - Generate pager messages
• ✅ Full POCSAG decoder - Decode pager messages from WAV files
• ✅ BCH(31,21) error correction
• ✅ Address encoding/decoding
• ✅ BCD numeric message encoding (function 0)
• ✅ 7-bit ASCII alphanumeric encoding (function 3)
• ✅ WAV audio generation and decoding (48kHz, 512/1200/2400 baud)
• ✅ AES-256/AES-128 encryption - Secure communications
• ✅ Compatible with PDW and multimon-ng
• ✅ JSON output support for API integration

Installation

# Install encoder
go install github.com/sqpp/pocsag-golang/cmd/pocsag@latest

# Install decoder
go install github.com/sqpp/pocsag-golang/cmd/pocsag-decode@latest

# Install burst encoder (multiple messages)
go install github.com/sqpp/pocsag-golang/cmd/pocsag-burst@latest

Or build from source:

git clone https://github.com/sqpp/pocsag-golang.git
cd pocsag-golang
go build ./cmd/pocsag
go build ./cmd/pocsag-decode
go build ./cmd/pocsag-burst

Usage

Encoder

Generate POCSAG messages as WAV audio files:

# Alphanumeric message (default)
pocsag --address 123456 --message "HELLO WORLD" --output message.wav
pocsag -a 123456 -m "HELLO WORLD" -o message.wav

# Numeric message (512 baud)
pocsag --address 999888 --message "0123456789" --function 0 --baud 512 --output numeric.wav
pocsag -a 999888 -m "0123456789" -f 0 -b 512 -o numeric.wav

# High speed message (2400 baud)
pocsag --address 123456 --message "FAST MSG" --baud 2400 --output fast.wav
pocsag -a 123456 -m "FAST MSG" -b 2400 -o fast.wav

# Encrypted message (AES-256)
pocsag --address 123456 --message "SECRET MESSAGE" --encrypt --key "mysecretkey" --output encrypted.wav
pocsag -a 123456 -m "SECRET MESSAGE" -e -k "mysecretkey" -o encrypted.wav

# JSON output (for API integration)
pocsag -a 123456 -m "TEST API" -o test.wav --json

Parameters:

• --address / -a: Pager address (RIC) - REQUIRED
  • Note: POCSAG addresses are automatically rounded to multiples of 8 (e.g., 1234567 → 1234560)
• --message / -m: Message text - REQUIRED
• --output / -o: Output WAV file (default: output.wav)
• --function / -f: Message type - 0 for numeric, 3 for alphanumeric (default: 3)
• --baud / -b: Baud rate - 512, 1200, or 2400 (default: 1200)
• --encrypt / -e: Enable AES-256 encryption
• --key / -k: Encryption key (required if --encrypt is used)
• --json / -j: Output result as JSON

Decoder

Decode POCSAG messages from WAV files:

pocsag-decode --input message.wav
pocsag-decode -i message.wav

# Specify baud rate
pocsag-decode -i message.wav --baud 512
pocsag-decode -i message.wav -b 2400

# JSON output (for API integration)
pocsag-decode -i message.wav --json

Output example:

POCSAG1200: Decoded messages:
Address:  123456  Function: 3  ALPHA    Message: HELLO WORLD

JSON output example:

{
  "success": true,
  "messages": [
    {
      "address": 123456,
      "function": 3,
      "message": "HELLO WORLD",
      "type": "alphanumeric"
    }
  ],
  "baud": 1200
}

Burst Encoder (Multiple Messages)

Send multiple messages in one transmission:

# Create JSON file with messages
cat > messages.json << 'EOF'
[
  {"address": 123456, "message": "FIRST MESSAGE", "function": 3},
  {"address": 789012, "message": "SECOND MESSAGE", "function": 3},
  {"address": 345678, "message": "0123456789", "function": 0}
]
EOF

# Generate burst
pocsag-burst --json messages.json --output burst.wav
pocsag-burst -j messages.json -o burst.wav

# JSON output
pocsag-burst -j messages.json --json-output
pocsag-burst -j messages.json -jo

Parameters:

• --json / -j: JSON input file with message array - REQUIRED
• --output / -o: Output WAV file (default: burst.wav)
• --baud / -b: Baud rate - 512, 1200, or 2400 (default: 1200)
• --json-output / -jo: Output result as JSON

JSON Format:

[
  {
    "address": 123456,
    "message": "Your message here",
    "function": 3
  }
]

• address: Pager address (RIC)
• message: Message text
• function: 0 for numeric, 3 for alphanumeric

JSON Output Example:

{
  "success": true,
  "output": "burst.wav",
  "messages": [
    {
      "address": 123456,
      "function": 3,
      "message": "FIRST MESSAGE",
      "type": "alphanumeric"
    },
    {
      "address": 789012,
      "function": 3,
      "message": "SECOND MESSAGE",
      "type": "alphanumeric"
    }
  ],
  "baud": 1200,
  "count": 2,
  "size": 44844
}

Library Usage

Encoding

package main

import (
    "os"
    pocsag "github.com/sqpp/pocsag-golang"
)

func main() {
    // Create alphanumeric message
    packet := pocsag.CreatePOCSAGPacket(123456, "HELLO WORLD", pocsag.FuncAlphanumeric)
    
    // Convert to WAV audio
    wavData := pocsag.ConvertToAudio(packet)
    
    // Save to file
    os.WriteFile("output.wav", wavData, 0644)
}

Decoding

package main

import (
    "fmt"
    "os"
    pocsag "github.com/sqpp/pocsag-golang"
)

func main() {
    // Read WAV file
    wavData, _ := os.ReadFile("message.wav")
    
    // Decode messages
    messages, err := pocsag.DecodeFromAudio(wavData)
    if err != nil {
        panic(err)
    }
    
    // Print decoded messages
    for _, msg := range messages {
        fmt.Println(msg.String())
    }
}

API Reference

Constants

• FuncNumeric (0) - Numeric messages
• FuncAlphanumeric (3) - Alphanumeric messages
• FrameSyncWord (0x7CD215D8) - POCSAG frame sync
• IdleCodeword (0x7A89C197) - Idle codeword

Encoding Functions

• CreatePOCSAGPacket(address uint32, message string, function uint8) []byte

  • Creates a complete POCSAG packet with preamble, sync, address, and message

• ConvertToAudio(pocsagData []byte) []byte

  • Converts POCSAG bytes to WAV audio (48kHz, 16-bit PCM, mono)

• EncodeAddress(address uint32, function uint8) uint32

  • Encodes an address codeword with BCH and parity

• Ascii7BitEncoder(message string) []byte

  • Encodes ASCII text to 7-bit format for alphanumeric messages

• NumericBCDEncoder(message string) []byte

  • Encodes numeric strings to BCD format (supports 0-9, space, -, [, ], U)

Decoding Functions

• DecodeFromAudio(wavData []byte) ([]DecodedMessage, error)

  • Decodes POCSAG messages from WAV audio data

• DecodeFromBinary(data []byte) ([]DecodedMessage, error)

  • Decodes POCSAG messages from raw binary data

• DecodeReader(r io.Reader) ([]DecodedMessage, error)

  • Decodes POCSAG from an io.Reader

Types

type DecodedMessage struct {
    Address   uint32
    Function  uint8
    Message   string
    IsNumeric bool
}

Encryption

POCSAG-GO supports modern encryption standards for secure communications:

Supported Encryption Methods

• AES-256: Military-grade encryption (default)
• AES-128: High-security encryption (alternative)
• CRC32 Integrity Verification: Prevents message tampering
• Base64 Encoding: Ensures POCSAG protocol compatibility

Security Features

• 🔐 Password-based key derivation using SHA256 hashing
• 🛡️ Random IV generation prevents replay attacks
• ✅ Message integrity verification with CRC32 checksums
• 🔄 Backward compatibility with non-encrypted messages

Encryption Process

Original Message → Add CRC32 → AES-256 Encrypt → Base64 Encode → POCSAG Packet

Decryption Process

POCSAG Packet → Base64 Decode → AES-256 Decrypt → Verify CRC32 → Original Message

Usage Examples

# Create encrypted message
pocsag -a 123456 -m "SECRET MESSAGE" -e -k "mysecretkey" -o encrypted.wav

# JSON output shows encryption status
pocsag -a 123456 -m "SECRET MESSAGE" -e -k "mysecretkey" --json

JSON Output Example:

{
  "success": true,
  "output": "encrypted.wav",
  "address": 123456,
  "function": 3,
  "message": "SECRET MESSAGE",
  "baud": 1200,
  "encrypted": true,
  "type": "alphanumeric",
  "size": 133164
}

Security Notes

• Key Management: Use strong, unique keys for each communication group
• Key Distribution: Securely share keys with intended recipients
• Compatibility: Encrypted messages appear as Base64-encoded data in multimon-ng
• Performance: Encryption adds minimal overhead to message processing

Testing with PDW / multimon-ng

The generated WAV files are compatible with:

• PDW (Paging Decode for Windows)
• multimon-ng - multimon-ng -t wav -a POCSAG1200 message.wav
• multimon-ng - multimon-ng -t wav -a POCSAG512 message.wav (512 baud)
• multimon-ng - multimon-ng -t wav -a POCSAG2400 message.wav (2400 baud)

Note: Our decoder properly handles message padding and strips null characters. Multimon-ng may occasionally display extra null characters for longer messages, but this doesn't affect the actual message content when decoded with our tools.

Credits

Encoder ported from pocsag-tool by hazardousfirmware.

License

BSD-2-Clause (same as original pocsag-tool)