Version 1.0 from 30.06.21 - Requires DIY-Thermocam V3 and firmware version >= 3.0.0

This guide describes how you can communicate with your DIY-Thermocam V3 over the USB serial connection.

The maximum transfer speed is 12 Mbit/s and is always active, no matter what baud rate you use to connect to the device from your PC. This allows you to receive thermal frames with high speed. The device needs to be turned on, connected to the PC over USB and set to live mode. The protocol uses big endian for transmission of multibyte values, which means MSB first, then LSB.

To see how the protocol is implemented inside the firmware in C, check out this file. The Thermal Live Viewer can be used on any Windows PC to use the protocol and communicate to the device.

Commands

Those are the commands that can be send from the PC to the DIY-Thermocam over the Serial Connection. Sometimes they provide additional information in the data field. An explanation about the different options is given in the "Payload Data" section below.

Each command returns either its own command ID as response if it was executed successfully (ack) and does not return any additional data or 0x00 if it failed to execute (nack). In case any special data is returned, it is described in the return data column.

CommandNamePayload LengthPayload DataReturn LengthReturn DataDescription
0x64SetStart0-1ack / nackSet the device into serial mode and waits for the next command from the list
0xC8SetEnd0-1ack / nackExit serial mode and set the device back to live mode
0x6EGetRawLimits0-4minTemp MSB, minTemp LSB, maxTemp MSB, maxTemp LSBGet the lepton raw limits (14-bit) for the next frame
0x6FGetRawData0-9600 / 384004800 / 19200 * (rawData[i] MSB, rawData[i] LSB)Get the lepton raw values for the next frame, 9600 byte (Lepton2) or 38400 byte (Lepton3); 14-bit raw values (0 … 16383) for each pixel, equivalent to infrared intensity
0x70GetConfigData0-10see Config Data belowGet the configuration data of the device, that does not change if not adjusted manually
0x72GetCalibData0-8two float, split to four bytes each, LSB first, MSB at the endGet the calibration data from the Lepton (offset and slope)
0x73GetSpotTemp0-4Float split into four bytes, LSB first, then MSBGet the spot temperature from the Lepton, in Fahrenheit or Celcius
0x75GetTempPoints0-38496 points (96 x 4), 2 bytes index, 2 bytes raw value, MSB first, then LSBGet the temperature points that are shown on the screen
0x78SetShutterRun0-1ack / nackRun the shutter flat-field-correction (FFC) on the Lepton
0x79SetShutterMode1uint8t - shuttermode (see Shutter Mode below)1ack / nackSet the Lepton shutter FFC mode to automatic or manual
0x7ASetFilterType1uint8t filtertype (see Filter Type below)1ack / nackSet the type of filter used to improve the image quality
0x7CGetBatteryStatus0-10 = 0% (empty), 100 = 100% (fully charged)Get the current battery status in percentage
0x7FGetDiagnostic0-1ack / nackGet the diagnostic information containing the hardware status
0x81GetFirmwareVersion0-2FWVersion MSB, FWVersion LSBGet the current firmware version installed on the device
0x82SetLimitType1uint8t limittype (see Limit Type below)1ack / nackSet limit type to limit locked or automatic mode
0x83SetTextColor1uint8t textcolor (see Text Color below)1ack / nackSet the text color used to display the elements in live mode
0x84SetColorScheme1uint8t colorscheme (see Color Scheme below)1ack / nackSet current color scheme used for the conversion
0x85SetTempFormat1uint8t tempformat (see Temperature Format below)1ack / nackSet the temperature format to Celsius or Fahrenheit
0x86SetShowSpot1uint8t showspot (see Show Spot below)1ack / nackShow spot temperature information in the image or not
0x87SetShowColorbar1uint8t showcolorbar (see Show Colorbar below)1ack / nackShow color bar information in the image or not
0x88SetShowMinMax1uint8t showminmax (see Show MinMax below)1ack / nackShow the hottest, coldest or both points in the image or not
0x89SetTempPoints38496 points (96 x 4 Byte): 2 byte index, 2 bytes value (see Temperature Points below)1ack / nackSet the temperature points to be shown on the screen (up to 96). The first two bytes are the index value that corresponds to the position in the thermal image (0 = (0,0) … 19200 = (159, 119)). The second two bytes are either set or not, depending on the point being disabled or enabled
0x8AGetHwVersion0-1see Hardware Version belowGet the hardware version of the device
0x8BSetRotation1uint8_t rotation (see Rotation below)1ack / nackSets the display rotation on the device
0x96GetRawFrame0-1 + 9600 / 38400 + 16see Raw Frame belowGet a raw frame containing the raw data and additional information (160x120)
0x97GetColorFrame0-1 + 9600 / 38400 + 16same as Raw Frame, but raw values are converted to RGB565 and filter is appliedGet a color frame containing RGB565 colors that represent the thermal image (160x120)
0x98GetDisplayFrame0-1 + 153600commandID is the same as for the Raw Frame, followed by RGB565 colors (2 byte) for each pixel on the displayGet a display frame containing RGB565 colors that represent the content of the display (320x240)
0x99GetFrameSave0-1ack / nackSave a frame + converted image (if activated)] to the internal storage of the Thermocam

Payload Data

Shutter Mode

ValueDescription
0x00Manual
0x01Automatic

Filter Type

ValueDescription
0x00Disabled
0x01Gaussian Blur
0x02Box Blur

Limit Type

ValueDescription
0x00Limits locked
0x01Auto mode, limits adjust

Text Color

ValueDescription
0x00White
0x01Black
0x02Red
0x03Green
0x04Blue

Color Scheme

ValueDescription
0x00Arctic
0x01Black-Hot
0x02Blue-Red
0x03Coldest
0x04Contrast
0x05Double-Rainbow
0x06Gray-Red
0x07Glowbow
0x08Grayscale
0x09Hottest
0x0AIronblack
0x0BLava
0x0CMedical
0x0DRainbow
0x0EWheel 1
0x0FWheel 2
0x10Wheel 3
0x11White-Hot
0x12Yellow

Temperature Format

ValueDescription
0x00Celsius
0x01Fahrenheit

Show Spot

ValueDescription
0x00Disabled
0x01Enabled

Show Colorbar

ValueDescription
0x00Disabled
0x01Enabled

Show MinMax

ValueDescription
0x00Disabled
0x01Minimum temperature only
0x02Maximum temperature only
0x03Minimum and maximum temperature

Temperature Points

ValueDescription
0x00Point on this index is disabled
0x01Point on this index is enabled

Rotation

ValueDescription
0x00Normal Orientation
0x01180° Rotated

Return Data

Config Data

  • leptonVersion (1 Byte): 0 = Lepton2 shutter, 1 = Lepton3 shutter, 2 = Lepton2 no shutter
  • rotationEnabled (1 Byte): 0 = Normal orientation, 1 = Device rotated by 180 degree
  • colorScheme (1 Byte): Number definitions can be looked up under Color Scheme above
  • tempFormat (1 Byte): 0 = Celsius, 1 = Fahrenheit
  • spotEnabled (1 Byte): 0 = Disabled, 1 = Spot temperature displayed
  • colorbarEnabled (1 Byte): 0 = Disabled, 1 = Colorbar displayed
  • minMaxEnabled (1 Byte): 0 = Disabled, 1 = Min, 2 = Max, 3 = Both
  • textColor (1 byte): 0 = White, 1 = Black, 2 = Red, 3 = Green, 4 = Blue
  • filtertype (1 byte): 0 = Disabled, 1 = Gaussian blur, 2 = Box blur
  • adjustLimits (1 Byte): 0 = Manual mode, limits fixed, 1 = Auto mode, limits adjust

Hardware Version

ValueDescription
0x01DIY-Thermocam V1
0x02DIY-Thermocam V2
0x03DIY-Thermocam V3

Raw Frame

  • commandId (1 byte):

    ValueDescription
    0xB4Push button was pressed short; user wants to save a thermal image (only used in Thermal Live Viewer)
    0xB5Touch screen was pressed short; user wants to save a visual image (only used in Thermal Live Viewer)
    0xB7No button pressed: normal frame, followed by the byte stream (should be used by default)
  • rawData (9600 (Lepton2.5) / 38400 (Lepton3.1R/3.5) byte): 14-bit raw values (0 … 16383) for each pixel, equivalent to infrared intensity
  • rawLimits (4 byte): minTemp MSB, minTemp LSB, maxTemp MSB, maxTemp LSB
  • spotTemp (4 byte): Float split into four bytes, LSB first, then MSB
  • calibData (8 byte): Two float offset and slope, split to four bytes each, LSB first, MSB at the end