SSDVClient Class Reference

Client for SSDV image transmission and reception. Encodes a baseline JPEG into 256-byte SSDV packets and reassembles received packets into a JPEG. The JPEG must be baseline DCT, greyscale or YCbCr, with dimensions that are multiples of 16 (max. 4080 x 4080). Encoder and decoder are derived from ssdv by Philip Heron, https://github.com/fsphil/ssdv (GPL-3.0). More...

#include <SSDV.h>

Public Member Functions
	SSDVClient (PhysicalLayer *phy, bool fec=true)
	Default constructor.
	~SSDVClient ()
	Destructor, releases the packet buffer and decoder state.
int16_t	begin (const char *callsign)
	Initialization method.
int16_t	setImage (const uint8_t *jpegData, size_t jpegLen, uint8_t quality=4, int16_t imageId=-1)
	Encode a JPEG image into SSDV packets. Any previously loaded image is discarded. The packets are stored on heap (numPackets() * 256 bytes), so the JPEG may be released afterwards. With RADIOLIB_STATIC_ONLY, a static buffer of RADIOLIB_SSDV_MAX_PACKETS packets is used instead, which only one SSDVClient instance can hold at a time. Does not affect an image that is being received.
uint16_t	numPackets ()
	Get the number of packets of the current image.
bool	isDone ()
	Check whether all packets of the current image have been sent.
uint16_t	currentPacketIndex ()
	Get the index of the next packet to be transmitted.
int16_t	transmit (uint16_t *packetId=NULL)
	Transmit the next packet. The sync word is redundant with the radio's own packet framing, so it is not transmitted, leaving 255 bytes to fit the maximum packet length of the radio.
void	clearImage ()
	Discard the current image and release the packet buffer.
int16_t	read (uint8_t *packet)
	Read a received packet from the radio and restore its sync word. The packet is not validated, call isValidPacket() on it.
int16_t	beginDecoder (uint8_t *jpegBuf, size_t jpegBufLen)
	Initialize the JPEG decoder. A safe output buffer size is (number of packets) * (payload length) + 2048 bytes, e.g. about 16 kB for 320 x 240 at quality 4.
int16_t	feedPacket (const uint8_t *packet)
	Feed a validated packet to the decoder. Packets must arrive in ascending order; missing packets are replaced by blank MCU blocks.
int16_t	getJpeg (uint8_t **jpegPtr, size_t *jpegLen)
	Get the reconstructed JPEG after feedPacket() returned RADIOLIB_SSDV_EOI.
int16_t	resetDecoder ()
	Reset the decoder to receive a new image into the same output buffer.
void	endDecoder ()
	Detach the decoder from its output buffer. The buffer is owned by the caller and is not released.

Static Public Member Functions
static int16_t	isValidPacket (uint8_t *packet, int16_t *errors=NULL)
	Validate a packet by its CRC. If that fails, Reed-Solomon correction is attempted (up to 16 symbol errors) and on success the corrected packet is written back.
static void	parseHeader (const uint8_t *packet, SSDVPacketInfo_t *info)
	Parse the header of a validated packet.

Detailed Description

Client for SSDV image transmission and reception. Encodes a baseline JPEG into 256-byte SSDV packets and reassembles received packets into a JPEG. The JPEG must be baseline DCT, greyscale or YCbCr, with dimensions that are multiples of 16 (max. 4080 x 4080). Encoder and decoder are derived from ssdv by Philip Heron, https://github.com/fsphil/ssdv (GPL-3.0).

Constructor & Destructor Documentation

SSDVClient()

SSDVClient::SSDVClient ( PhysicalLayer * phy, bool fec = true )

explicit

Default constructor.

Parameters

phy	Pointer to the wireless module providing PhysicalLayer communication.
fec	Set to true for Normal mode (205-byte payload + Reed-Solomon FEC, e.g. for FSK), or false for No-FEC mode (237-byte payload, e.g. for LoRa which has its own FEC).

Member Function Documentation

begin()

int16_t SSDVClient::begin

(

const char *

callsign

)

Initialization method.

Parameters

callsign

Station callsign, up to 6 characters: A-Z, a-z, 0-9 and '-'.

Returns

Status Codes

beginDecoder()

int16_t SSDVClient::beginDecoder	(	uint8_t *	jpegBuf,
		size_t	jpegBufLen )

Initialize the JPEG decoder. A safe output buffer size is (number of packets) * (payload length) + 2048 bytes, e.g. about 16 kB for 320 x 240 at quality 4.

Parameters

jpegBuf	Output buffer for the reconstructed JPEG.
jpegBufLen	Size of the output buffer in bytes.

Returns

Status Codes

currentPacketIndex()

uint16_t SSDVClient::currentPacketIndex

(

)

Get the index of the next packet to be transmitted.

Returns

Packet index, equal to numPackets() when done.

feedPacket()

int16_t SSDVClient::feedPacket

(

const uint8_t *

packet

)

Feed a validated packet to the decoder. Packets must arrive in ascending order; missing packets are replaced by blank MCU blocks.

Parameters

packet

256-byte packet.

Returns

RADIOLIB_SSDV_EOI when the image is complete, otherwise Status Codes

getJpeg()

int16_t SSDVClient::getJpeg	(	uint8_t **	jpegPtr,
		size_t *	jpegLen )

Get the reconstructed JPEG after feedPacket() returned RADIOLIB_SSDV_EOI.

Parameters

jpegPtr	Will be set to the start of the JPEG in the output buffer.
jpegLen	Will be set to the length of the JPEG in bytes.

Returns

Status Codes

isDone()

bool SSDVClient::isDone

(

)

Check whether all packets of the current image have been sent.

Returns

True if all packets were sent or no image is loaded, false otherwise.

isValidPacket()

int16_t SSDVClient::isValidPacket ( uint8_t * packet, int16_t * errors = NULL )

static

Validate a packet by its CRC. If that fails, Reed-Solomon correction is attempted (up to 16 symbol errors) and on success the corrected packet is written back.

Parameters

packet	256-byte packet.
errors	If not NULL, will be set to the number of corrected symbol errors.

Returns

Status Codes

numPackets()

uint16_t SSDVClient::numPackets

(

)

Get the number of packets of the current image.

Returns

Number of packets, 0 if no image is loaded.

parseHeader()

void SSDVClient::parseHeader ( const uint8_t * packet, SSDVPacketInfo_t * info )

static

Parse the header of a validated packet.

Parameters

packet	256-byte packet.
info	Structure to fill.

read()

int16_t SSDVClient::read

(

uint8_t *

packet

)

Read a received packet from the radio and restore its sync word. The packet is not validated, call isValidPacket() on it.

Parameters

packet

Buffer of at least 256 bytes.

Returns

Status Codes

resetDecoder()

int16_t SSDVClient::resetDecoder

(

)

Reset the decoder to receive a new image into the same output buffer.

Returns

Status Codes

setImage()

int16_t SSDVClient::setImage	(	const uint8_t *	jpegData,
		size_t	jpegLen,
		uint8_t	quality = 4,
		int16_t	imageId = -1 )

Encode a JPEG image into SSDV packets. Any previously loaded image is discarded. The packets are stored on heap (numPackets() * 256 bytes), so the JPEG may be released afterwards. With RADIOLIB_STATIC_ONLY, a static buffer of RADIOLIB_SSDV_MAX_PACKETS packets is used instead, which only one SSDVClient instance can hold at a time. Does not affect an image that is being received.

Parameters

jpegData	Complete JPEG file.
jpegLen	Length of the JPEG in bytes.
quality	Quality level 0 - 7, corresponding to JPEG quality 13, 18, 29, 43, 50, 71, 86 and 100. Defaults to 4.
imageId	Image ID 0 - 255, or -1 to increment the ID of the previous image. Defaults to -1.

Returns

Status Codes

transmit()

int16_t SSDVClient::transmit

(

uint16_t *

packetId = NULL

)

Transmit the next packet. The sync word is redundant with the radio's own packet framing, so it is not transmitted, leaving 255 bytes to fit the maximum packet length of the radio.

Parameters

packetId

If not NULL, will be set to the index of the transmitted packet.

Returns

Number of packets transmitted so far, or a negative Status Codes on error.

---

The documentation for this class was generated from the following files:

• src/protocols/SSDV/SSDV.h
• src/protocols/SSDV/SSDV.cpp