The core class for DumbDisplay; everything starts here. The most important argument to DumbDisplay is an DDInputOutput object. For an example, please refer to Blink Test With Virtual Display, DumbDisplay More...

#include <dumbdisplay.h>

Public Member Functions
	DumbDisplay (DDInputOutput *pIO, uint16_t sendBufferSize=DD_DEF_SEND_BUFFER_SIZE, long idleTimeout=DD_DEF_IDLE_TIMEOUT)

void	connect ()

bool	connected () const

int	getConnectVersion () const

int	getCompatibilityVersion () const

void	setFeedbackSingleClickOnly (bool singleClickOnly=true)

void	configAutoPin (const String &layoutSpec=DD_AP_VERT, bool autoShowHideLayers=false)

void	addRemainingAutoPinConfig (const String &remainingLayoutSpec)
	add the "auto pin" config for layers not included in "auto pin" set by configAutoPin()

void	configPinFrame (int xUnitCount=100, int yUnitCount=100, bool autoShowHideLayers=false)

void	pinLayer (DDLayer *pLayer, int uLeft, int uTop, int uWidth, int uHeight, const String &align="")

void	pinAutoPinLayers (const String &layoutSpec, int uLeft, int uTop, int uWidth, int uHeight, const String &align="")

MbDDLayer *	createMicrobitLayer (int width=5, int height=5)
	create a Microbit-like layer

TurtleDDLayer *	createTurtleLayer (int width, int height)
	create a Turtle-like layer

LedGridDDLayer *	createLedGridLayer (int colCount=1, int rowCount=1, int subColCount=1, int subRowCount=1)
	create a LED-grid layer

LcdDDLayer *	createLcdLayer (int colCount=16, int rowCount=2, int charHeight=0, const String &fontName="")
	create a LCD layer

SelectionDDLayer *	createSelectionLayer (int colCount=16, int rowCount=2, int horiSelectionCount=1, int vertSelectionCount=1, int charHeight=0, const String &fontName="", bool canDrawDots=true, float selectionBorderSizeCharHeightFactor=0.3)
	create a "selection" layer

GraphicalDDLayer *	createGraphicalLayer (int width, int height)

SevenSegmentRowDDLayer *	create7SegmentRowLayer (int digitCount=1)

JoystickDDLayer *	createJoystickLayer (int maxStickValue=1023, const String &directions="", float stickSizeFactor=1.0)

PlotterDDLayer *	createPlotterLayer (int width, int height, int pixelsPerSecond=10)
	create a plotter layer

PlotterDDLayer *	createFixedRatePlotterLayer (int width, int height, int pixelsPerScale=5)

TomTomMapDDLayer *	createTomTomMapLayer (const String &mapKey, int width, int height)

TerminalDDLayer *	createTerminalLayer (int width, int height)

WebViewDDLayer *	createWebViewLayer (int width, int height, const String &jsObjectName="DD")

DumbDisplayWindowDDLayer *	createDumbDisplayWindowLayer (int width, int height)

BasicDDTunnel *	createBasicTunnel (const String &endPoint, bool connectNow=true, int8_t bufferSize=DD_TUNNEL_DEF_BUFFER_SIZE)

JsonDDTunnel *	createJsonTunnel (const String &endPoint, bool connectNow=true, int8_t bufferSize=DD_TUNNEL_DEF_BUFFER_SIZE)

JsonDDTunnel *	createFilteredJsonTunnel (const String &endPoint, const String &fileNames, bool connectNow=true, int8_t bufferSize=DD_TUNNEL_DEF_BUFFER_SIZE)

SimpleToolDDTunnel *	createImageDownloadTunnel (const String &endPoint, const String &imageName, boolean redownload=true)

BasicDDTunnel *	createDateTimeServiceTunnel ()

BasicDDTunnel *	createGeneralServiceTunnel ()

GpsServiceDDTunnel *	createGpsServiceTunnel ()

ObjectDetectDemoServiceDDTunnel *	createObjectDetectDemoServiceTunnel (int scaleToWidth=0, int scaleToHeight=0, int maxNumObjs=1)

ImageRetrieverDDTunnel *	createImageRetrieverTunnel ()

void	deleteTunnel (DDTunnel *pTunnel)
	if finished using a "tunnel", delete it to release resource

void	backgroundColor (const String &color)

void	recordLayerSetupCommands ()
	basically, functions the same as recordLayerCommands()

void	playbackLayerSetupCommands (const String &layerSetupPersistId)

void	recordLayerCommands ()

void	playbackLayerCommands ()
	playback recorded commands (unfreeze the display)

void	stopRecordLayerCommands (const String &saveId="", bool persistSave=false)

void	saveLayerCommands (const String &id, bool persist=false, bool stopAfterSave=false)

void	loadLayerCommands (const String &id)

void	capture (const String &imageFileName, int width, int height)

void	sendNoOp ()
	send "no-op" command

void	writeComment (const String &comment)
	write out a comment to DD app

void	tone (uint32_t freq, uint32_t duration)
	make DD app sound a tone

void	notone ()

void	playSound (const String &soundName)
	make DD app play the sound of the given sound file

void	stopSound ()

void	saveSound8 (const String &soundName, const int8_t *bytes, int sampleCount, int sampleRate, int numChannels=1)
	save 8-bit sound with the given sound samples

void	saveSound16 (const String &soundName, const int16_t *data, int sampleCount, int sampleRate, int numChannels=1)
	save 16-bit sound with the given sound samples

void	cacheSound8 (const String &soundName, const int8_t *bytes, int sampleCount, int sampleRate, int numChannels=1)
	cache 8-bit sound with the given sound samples

void	cacheSound16 (const String &soundName, const int16_t *data, int sampleCount, int sampleRate, int numChannels=1)
	cache 16-bit sound with the given sound samples

void	saveCachedSound (const String &soundName)
	save the cached sound

void	saveCachedSoundAsH (const String &soundName)

int	streamSound8 (int sampleRate, int numChannels=1)
	stream sound 8-bit sample (for playing sound)

int	streamSound16 (int sampleRate, int numChannels=1)
	stream sound 16-bit sample (for playing sound)

int	saveSoundChunked8 (const String &soundName, int sampleRate, int numChannels=1)

int	saveSoundChunked16 (const String &soundName, int sampleRate, int numChannels=1)

int	cacheSoundChunked8 (const String &soundName, int sampleRate, int numChannels=1)

int	cacheSoundChunked16 (const String &soundName, int sampleRate, int numChannels=1)

void	sendSoundChunk8 (int chunkId, const int8_t *bytes, int sampleCount, bool isFinal=false)
	send 8-bit sound data chunk for saving/caching after calling saveSoundChunked8() or cacheSoundChunked8()

void	sendSoundChunk16 (int chunkId, const int16_t *data, int sampleCount, bool isFinal=false)
	send 16-bit sound data chunk for saving/caching after calling saveSoundChunked16() or cacheSoundChunked16()

void	saveImage (const String &imageName, const uint8_t *bytes, int byteCount)
	svae image with the given image data

void	savePixelImage (const String &imageName, const uint8_t *bytes, int width, int height, const String &color="", char compressMethod=0)
	save single-bit "pixel" image (i.e. B&W image) with the given image data

void	savePixelImage16 (const String &imageName, const uint16_t *data, int width, int height, const String &options="", char compressMethod=0)
	save 16-bit "pixel" image (i.e. 565 RGB image) with the given image data

void	savePixelImageGS (const String &imageName, const uint8_t *data, int width, int height, const String &options="", char compressMethod=0)
	save grayscale "pixel" image with the given image data

void	stitchImages (const String &imageNames, const String &asImageName)

void	alert (const String &message, const String &title="")
	pop up a dialog to alert

void	reorderLayer (DDLayer *pLayer, const String &how)

void	deleteLayer (DDLayer *pLayer)
	if layer is no longer used; delete it to release resources

void	walkLayers (void(walker)(DDLayer ))
	loop through all the existing layers calling the function passed in

void	setIdleCallback (DDIdleCallback idleCallback)

void	setConnectVersionChangedCallback (DDConnectVersionChangedCallback connectVersionChangedCallback)

bool	canPrintToSerial ()
	check if it is safe to print to Serial

void	logToSerial (const String &logLine, bool force=false)
	log line to Serial; if it is not safe to output to Serial, will write comment with DumbDisplay::writeComment() instead

void	log (const String &logLine, boolean isError=false)
	like to Serial (if safe to do so); and if connected, will log as comment to DD as well

bool	connectPassive (DDConnectPassiveStatus *pStatus=NULL)

void	masterReset ()

void	debugSetup (DDDebugInterface *debugInterface)

void	debugOnly (int i)

Detailed Description

The core class for DumbDisplay; everything starts here. The most important argument to DumbDisplay is an DDInputOutput object. For an example, please refer to Blink Test With Virtual Display, DumbDisplay

Member Function Documentation

◆ backgroundColor()

void DumbDisplay::backgroundColor ( const String & color )

set DD background color

Parameters

color DD_COLOR_XXX; DD_RGB_COLOR(...); can also be common "color name"

◆ cacheSoundChunked16()

int DumbDisplay::cacheSoundChunked16	(	const String &	soundName,
		int	sampleRate,
		int	numChannels = `1`
	)

initiate caching of 16-bit sound sound chunked; use sendSoiundChunk16() to send sound data

◆ cacheSoundChunked8()

int DumbDisplay::cacheSoundChunked8	(	const String &	soundName,
		int	sampleRate,
		int	numChannels = `1`
	)

initiate caching of 8-bit sound sound chunked; use sendSoiundChunk8() to send sound data

◆ capture()

void DumbDisplay::capture	(	const String &	imageFileName,
		int	width,
		int	height
	)

capture and save display as image

Parameters

imageFileName	name of image file; if it ends with ".png", saved image format will be PNG; other, saved image format will be JPEG *‍/
width	width of the display on which to render the layers
height	height of the display on which to render the layers

Attention: old file with the same name will be replaced

◆ configAutoPin()

void DumbDisplay::configAutoPin	(	const String &	layoutSpec = `DD_AP_VERT`,
		bool	autoShowHideLayers = `false`
	)

configure "auto pinning of layers" with the layer spec provided

horizontal: H(*)
vertical: V(*)
or nested, like H(0+V(1+2)+3); where 0/1/2/3 are the layer ids
consider using the macros DD_AP_XXX
Parameters

layoutSpec the layout specification

autoShowHideLayers auto set layer visible (visibility) according whether the layer is specified in the layoutSpec or not; false by default

◆ configPinFrame()

void DumbDisplay::configPinFrame	(	int	xUnitCount = `100`,
		int	yUnitCount = `100`,
		bool	autoShowHideLayers = `false`
	)

configure "pin frame" to be x-units by y-units (default 100x100)

Parameters

autoShowHideLayers auto set layer visible (visibility) according whether the layer is specified in the layoutSpec or not; false by default

See also: pinLayer()

◆ connect()

void DumbDisplay::connect ( )

explicitly make connection (blocking); implicitly called in situations like create a layer

◆ connected()

bool DumbDisplay::connected ( ) const

Returns: connected or not

◆ connectPassive()

bool DumbDisplay::connectPassive ( DDConnectPassiveStatus * pStatus = NULL )

make connection passively; i.e. will not block, but will require continuous calling for making connection

Returns: connection made or not (note that even if connection lost and requires reconnecting, it is still considered connected)

Since: 0.9.8-r1

Note: if you will not be making use of "passive" connection, you can disable it by defining DD_NO_PASSIVE_CONNECT in order to reduce footprint

◆ create7SegmentRowLayer()

SevenSegmentRowDDLayer * DumbDisplay::create7SegmentRowLayer ( int digitCount = 1 )

create a 7-segment layer

Parameters

digitCount show how many digits; 1 by default

See also: SevenSegmentRowDDLayer

◆ createBasicTunnel()

BasicDDTunnel * DumbDisplay::createBasicTunnel	(	const String &	endPoint,
		bool	connectNow = `true`,
		int8_t	bufferSize = `DD_TUNNEL_DEF_BUFFER_SIZE`
	)

create a "tunnel" for accessing the Web

Note: if not connect now, need to connect via reconnect()

See also: BasicDDTunnel

◆ createDateTimeServiceTunnel()

BasicDDTunnel * DumbDisplay::createDateTimeServiceTunnel ( )

◆ createDumbDisplayWindowLayer()

DumbDisplayWindowDDLayer * DumbDisplay::createDumbDisplayWindowLayer	(	int	width,
		int	height
	)

create a DumbDisplay "window" layer

See also: DumbDisplayDDLayer

◆ createFilteredJsonTunnel()

JsonDDTunnel * DumbDisplay::createFilteredJsonTunnel	(	const String &	endPoint,
		const String &	fileNames,
		bool	connectNow = `true`,
		int8_t	bufferSize = `DD_TUNNEL_DEF_BUFFER_SIZE`
	)

create a JSON 'tunnel' for thing like making RESTful calls; with result filtered

Note: if not connect now, need to connect via reconnect()

Parameters

fieldNames comma-delimited list of field names to accept; note that matching is "case-insensitive containment match"

See also: JsonDDTunnel

◆ createFixedRatePlotterLayer()

PlotterDDLayer * DumbDisplay::createFixedRatePlotterLayer	(	int	width,
		int	height,
		int	pixelsPerScale = `5`
	)

create a fixed-rate plotter layer i.e. it will assume fixe-rate of PlotterDDLayer::set()

See also: PlotterDDLayer

◆ createGeneralServiceTunnel()

BasicDDTunnel * DumbDisplay::createGeneralServiceTunnel ( )

create a general "service tunnel" for purposes like getting date-time info from phone; use reconnectTo() with commands like

now – e.g now:yyyy-MM-dd-hh-mm-ss where yyyy-MM-dd-hh-mm-ss is the format
now-millis
confirm – pop up a dialog to confirm; e.g. confirm?title=Confirm&message=Are%20you%20sure%3F&ok=Yes&cancel=No
See also
BasicDDTunnel

◆ createGpsServiceTunnel()

GpsServiceDDTunnel * DumbDisplay::createGpsServiceTunnel ( )

create a "service tunnel" for getting GPS info from phone

See also: GpsServiceDDTunnel

◆ createGraphicalLayer()

GraphicalDDLayer * DumbDisplay::createGraphicalLayer	(	int	width,
		int	height
	)

create a graphical LCD layer

See also: GraphicalDDLayer

◆ createImageDownloadTunnel()

SimpleToolDDTunnel * DumbDisplay::createImageDownloadTunnel	(	const String &	endPoint,
		const String &	imageName,
		boolean	redownload = `true`
	)

create a "tunnel" to download image from the web, and save the downloaded image to phone; you will get result in JSON format: {"result":"ok"} or {"result":"failed"} for simplicity, use SimpleToolDDTunnel.checkResult() to check the result

See also: SimpleToolDDTunnel

◆ createJoystickLayer()

JoystickDDLayer * DumbDisplay::createJoystickLayer	(	int	maxStickValue = `1023`,
		const String &	directions = `""`,
		float	stickSizeFactor = `1.0`
	)

create a joystick layer:

will send joystick positions as "feedback", and hence "feedback" is automatically enabled;

initial position is (0, 0)

Parameters

maxStickValue	the max value of the stick; e.g. 255 or 1023 (the default); min is 15
directions	"lr" or "hori": left-to-right; "tb" or "vert": top-to-bottom; "rl": right-to-left; "bt": bottom-to-top; use "+" combines the above like "lr+tb" to mean both directions; "" the same as "lr+tb"
stickSizeFactor	the size factor of the stick (UI); 1 by default

See also: JoystickDDLayer

◆ createJsonTunnel()

JsonDDTunnel * DumbDisplay::createJsonTunnel	(	const String &	endPoint,
		bool	connectNow = `true`,
		int8_t	bufferSize = `DD_TUNNEL_DEF_BUFFER_SIZE`
	)

create a JSON 'tunnel' for thing like making RESTful calls

Note: if not connect now, need to connect via reconnect()

See also: BasicDDTunnel

◆ createObjectDetectDemoServiceTunnel()

ObjectDetectDemoServiceDDTunnel * DumbDisplay::createObjectDetectDemoServiceTunnel	(	int	scaleToWidth = `0`,
		int	scaleToHeight = `0`,
		int	maxNumObjs = `1`
	)

create a "service tunnel" for getting object detection info from phone; model used is the demo model mobilenetv1.tflite

See also: ObjectDetectDemoServiceDDTunnel

◆ createTerminalLayer()

TerminalDDLayer * DumbDisplay::createTerminalLayer	(	int	width,
		int	height
	)

create a terminal layer

See also: TerminalDDLayer

◆ createTomTomMapLayer()

TomTomMapDDLayer * DumbDisplay::createTomTomMapLayer	(	const String &	mapKey,
		int	width,
		int	height
	)

create a TomTom map layer

Parameters

mapKey should be provided; plesae visit TomTom's website to get one of your own if pass in "" as mapKey, will use my testing one

See also: TomTomMapDDLayer

◆ createWebViewLayer()

WebViewDDLayer * DumbDisplay::createWebViewLayer	(	int	width,
		int	height,
		const String &	jsObjectName = `"DD"`
	)

create a WebView layer

See also: WebViewDDLayer

◆ debugSetup()

void DumbDisplay::debugSetup ( DDDebugInterface * debugInterface )

set debug use callback

Parameters

debugInterface a concrete implementation of DDDebugInterface

◆ getCompatibilityVersion()

int DumbDisplay::getCompatibilityVersion ( ) const

Returns: compatibility version

Note: only meaningful after connection

◆ getConnectVersion()

int DumbDisplay::getConnectVersion ( ) const

Returns: the version of the connection, which when reconnected will be bumped up; note that if not connected, version will be 0

◆ loadLayerCommands()

void DumbDisplay::loadLayerCommands ( const String & id )

load saved commands (as if recording those commands)

recording started or not, will add the commands to the buffer
afterward, will keep recording
use playbackLayerCommands() to playback loaded commands

◆ masterReset()

void DumbDisplay::masterReset ( )

"master reset" will: . disconnect from DD app (if connected) . delete all created layers and tunnels; hence, DO NOT use the pointers to them after "master reset" . DumbDisplay object will be just like at initial state; it will not be deleted

Since: 0.9.8-r1

◆ pinAutoPinLayers()

void DumbDisplay::pinAutoPinLayers	(	const String &	layoutSpec,
		int	uLeft,
		int	uTop,
		int	uWidth,
		int	uHeight,
		const String &	align = `""`
	)

pin "auto pin" layers @ some position, like pinLayer()

Parameters

layoutSpec	the "auto pin" layout specification to pin; see configAutoPin() for how spec is constructed
align	(e.g. "LB") – left align "L"; right align "R"; top align "T"; bottom align "B"; default is center align *‍/

◆ pinLayer()

void DumbDisplay::pinLayer	(	DDLayer *	pLayer,
		int	uLeft,
		int	uTop,
		int	uWidth,
		int	uHeight,
		const String &	align = `""`
	)

pin a layer @ some position of an imaginary grid of "pin grame"

the imaginary grid size can be configured when calling connect() – default is 100x100
the input align (e.g. "LB") – left align "L"; right align "R"; top align "T"; bottom align "B"; default is center align

◆ playbackLayerSetupCommands()

void DumbDisplay::playbackLayerSetupCommands ( const String & layerSetupPersistId )

basically, functions the same as playbackLayerCommands(). additionally:

save and persist the layer commands
enable DumbDisplay reconnect feature – tells the layer setup commands to use when DumbDisplay reconnects

◆ recordLayerCommands()

void DumbDisplay::recordLayerCommands ( )

start recording layer commands (of any layers); and sort of freeze the display, until playback

◆ reorderLayer()

void DumbDisplay::reorderLayer	(	DDLayer *	pLayer,
		const String &	how
	)

reorder the layer (by moving one layer in the z-order plane)

Parameters

how	can be "T" for top; or "B" for bottom; "U" for up; or "D" for down

◆ saveCachedSoundAsH()

void DumbDisplay::saveCachedSoundAsH ( const String & soundName )

save the cached sound as C header file (.h) @warn this is experimental

◆ saveLayerCommands()

void DumbDisplay::saveLayerCommands	(	const String &	id,
		bool	persist = `false`,
		bool	stopAfterSave = `false`
	)

save the recorded commands (continue recording or not depends on parameter passed in ); any pre-existed saved commands with the same id will be replaced with the recording commands (delete if not recording)

Parameters

id	identifier of the recorded commands, overwriting and previous one; if not recording, will delete previous recorded commands
persist	store it to your phone as well
stopAfterSave	stop recording after saving

◆ saveSoundChunked16()

int DumbDisplay::saveSoundChunked16	(	const String &	soundName,
		int	sampleRate,
		int	numChannels = `1`
	)

initiate saving of 16-bit sound sound chunked; use sendSoiundChunk16() to send sound data

◆ saveSoundChunked8()

int DumbDisplay::saveSoundChunked8	(	const String &	soundName,
		int	sampleRate,
		int	numChannels = `1`
	)

initiate saving of 8-bit sound sound chunked; use sendSoiundChunk8() to send sound data

◆ setConnectVersionChangedCallback()

void DumbDisplay::setConnectVersionChangedCallback ( DDConnectVersionChangedCallback connectVersionChangedCallback )

set callback when version changed (e.g. reconnected after disconnect)

Parameters

connectVersionChangedCallback the callback function; see DDConnectVersionChangedCallback

◆ setFeedbackSingleClickOnly()

void DumbDisplay::setFeedbackSingleClickOnly ( bool singleClickOnly = true )

by default, "long press feedback" and "double click feedback" is enabled; however, this makes "click feedback" detection less responsive; one remedy is to set for "single click feedback" only

◆ setIdleCallback()

void DumbDisplay::setIdleCallback ( DDIdleCallback idleCallback )

set 'idle callback', which will be called repeatedly in 2 situations:

no connection response while connecting
detected no 'keep alive' signal (i.e. reconnecting)
Parameters

idleCallback the callback function; see DDIdleCallback

◆ stitchImages()

void DumbDisplay::stitchImages	(	const String &	imageNames,
		const String &	asImageName
	)

stitch images together

Parameters

imageNames	'+' delimited
asImageName	name for the stitched image

◆ stopRecordLayerCommands()

void DumbDisplay::stopRecordLayerCommands	(	const String &	saveId = `""`,
		bool	persistSave = `false`
	)

stop recording commands (if not saved, will forget what recorded)

Parameters

saveId	if provided, save like calling saveLayerCommands(); otherwise, forget what have been recording
persistSave	if save, store it to your phone as well

layoutSpec	the layout specification
autoShowHideLayers	auto set layer visible (visibility) according whether the layer is specified in the layoutSpec or not; false by default

Public Member Functions

Detailed Description

Member Function Documentation

◆ backgroundColor()

◆ cacheSoundChunked16()

◆ cacheSoundChunked8()

◆ capture()

◆ configAutoPin()

◆ configPinFrame()

◆ connect()

◆ connected()

◆ connectPassive()

◆ create7SegmentRowLayer()

◆ createBasicTunnel()

◆ createDateTimeServiceTunnel()

◆ createDumbDisplayWindowLayer()

◆ createFilteredJsonTunnel()

◆ createFixedRatePlotterLayer()

◆ createGeneralServiceTunnel()

◆ createGpsServiceTunnel()

◆ createGraphicalLayer()

◆ createImageDownloadTunnel()

◆ createJoystickLayer()

◆ createJsonTunnel()

◆ createObjectDetectDemoServiceTunnel()

◆ createTerminalLayer()

◆ createTomTomMapLayer()

◆ createWebViewLayer()

◆ debugSetup()

◆ getCompatibilityVersion()

◆ getConnectVersion()

◆ loadLayerCommands()

◆ masterReset()

◆ pinAutoPinLayers()

◆ pinLayer()

◆ playbackLayerSetupCommands()

◆ recordLayerCommands()

◆ reorderLayer()

◆ saveCachedSoundAsH()

◆ saveLayerCommands()

◆ saveSoundChunked16()

◆ saveSoundChunked8()

◆ setConnectVersionChangedCallback()

◆ setFeedbackSingleClickOnly()

◆ setIdleCallback()

◆ stitchImages()

◆ stopRecordLayerCommands()