Last edited · 14 revisions  

 


Binary Overlay Format Specification

Starting with firmware version 0.x.15, the camera always includes a binary timestamp in the last row of each frame. The binary timestamp uses 128 pixels and is repeated to fill the full frame width. Information is encoded in the lower 8 bits of each pixel in big-endian format. The overlay contains two sections, a fixed 96-pixel data section and a variable 32-pixel messages section.

The following information is available in the 80-pixel data section:

  • Offset - Length - Title - Description
  • 0 - 4 - Preamble - fixed 5C 54 53 3A
  • 4 - 2 - Overlay Format Version
    • fixed 00 01 for versions before 0.x.28
    • fixed 00 02 for versions 0.x.28 and higher; these include the camera status in the timestamp, starting at offset 80
    • fixed 00 03 for versions 0.x.31 and higher; these include the current fix state and number of satellites at pos. 74 and 75
    • fixed 00 04 for versions 0.x.35 and higher; these include the altitude above sea level in mm at offset 76
  • 6 - 2 - FPGA firmware Version
  • 8 - 12 - Start timestamp - YY MM DD HH MM SS ns-ns-ns-ns flags
    • ns is a 4-byte nanoseconds field and goes from 0 to 999999999
    • bit 0 in the flags indicates a valid time (due to a current or previous GNSS sync)
  • 20 - 12 - End timestamp - same format as start timestamp
  • 32 - 4 - reserved - 00 00 00 00
  • 36 - 4 - frame number - 4-byte unsigned frame counter
  • 40 - 2 - frame width
  • 42 - 2 - frame height
  • 44 - 1 - horizontal binning - add 1 to the value (e.g. value is 3 for 4x binning)
  • 45 - 1 - vertical binning - add 1 to the value
  • 46 - 2 - reserved - 00 00
  • 48 - 2 - signal multiplication M - multiplier used in compensating gain from binning; raw pixels are multiplied with (M/D) before sending them to the host.
  • 50 - 2 - signal division D - divider
  • 52 - 8 - integration time - split in a 32-bit unsigned number of seconds and a 32-bit number of nanoseconds
  • 60 - 2 - gain index
  • 62 - 2 - black level - indicates the value of the darkest pixel in the frame, before adding overlays
  • 64 - 4 - gps lattitude - divide by 1E7 to get number of degrees; MSB is 1 for south, 0 for north
  • 68 - 4 - gps longitude - divide by 1E7 to get number of degrees; MSB is 1 for west, 0 for east
  • 72 - 2 - gps accuracy - position accuracy in meters as reported by the gps receiver module
  • 74 - 1 - gps fix state
    • [000000 | dateTimeFullyResolved | validFix]
  • 75 - 1 - gps number of Satellite Vehicles
  • 76 - 4 - gps height above sea level (mm)
  • 80 - 4 - camera status flags
    • [00 | marker1 | marker2 || 0 | markers_enabled | overlay_mode:2 ]
    • [00 | 4digit_mode | 0 || gpo_mode:2 | led_control:2 ]
    • [0000 || clamp | 8bit | invert | 0]
    • [0000 || flip_mode:2 | 00]
  • 84 - 4 - camera status information
    • gain
    • [0000||0000]
    • exposure time (MSB)
    • exposure time (LSB)
  • 88 - 4 - USB PHY info
    • [tooManyPhyErrors:1 | 0 | phyErrCtr:14]
    • [phyErrFlags:16]
  • 92 - 4 - USB LNK info
    • [usbVersion:2 | lnkErrCtr:14]
    • [lnkErrFlags:16]

Messages in the 48-pixel messages section are currently not implemented, but the following messages have been planned:

  • satellite visibility and signal strength information
  • information on the internal time synchronisation, e.g. lock to 1pps
  • error and warning messages from the camera, e.g. issues with the USB link
  • ...