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, all 256 bytes including sync word. Intended for RTTY/FSK.
int16_t	transmitLoRa (uint16_t *packetId=NULL)
	Transmit the next packet without the sync word (255 bytes), to fit the LoRa payload limit.
void	clearImage ()
	Discard the current image and release the packet buffer.
int16_t	read (uint8_t *packet)
	Read a received packet from the radio. 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 RTTY/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. 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, all 256 bytes including sync word. Intended for RTTY/FSK.

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.

◆ transmitLoRa()

int16_t SSDVClient::transmitLoRa ( uint16_t * packetId = NULL )

Transmit the next packet without the sync word (255 bytes), to fit the LoRa payload limit.

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

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SSDVClient()

Member Function Documentation

◆ begin()

◆ beginDecoder()

◆ currentPacketIndex()

◆ feedPacket()

◆ getJpeg()

◆ isDone()

◆ isValidPacket()

◆ numPackets()

◆ parseHeader()

◆ read()

◆ resetDecoder()

◆ setImage()

◆ transmit()

◆ transmitLoRa()