API for HW dive computer drivers. More...

#include <HardwareOperations.h>

Inheritance diagram for HardwareOperations:

Protected Member Functions
QStringList	listBluetoothPorts () const
	List serial ports for Bluetooth based devices. More...

QStringList	listUSBPorts () const
	List serial ports for USB based devices. More...

Protected Attributes
Serial	_serial
	Communication port used for all I/O operations. More...

Class management
Managing the hierarchy of driver classes used to handle the various existing H&W devices.
virtual	~HardwareOperations ()
	mandatory (and empty) virtual descructor in the base class. More...

virtual QString	model () const =0
	The name of the computer driver. More...

Serial &	serial ()
	Gives access to serial port in use. Used for other high and low level operations, eg. in OSTC Planner. More...

Introspection
Methods available to ask the connected device what it does support, and how to manage it.
enum	HardwareOption { HW_CHARGEABLE_BATTERY = 0x01, HW_LIGHT_SENSOR = 0x02, HW_S8_COM = 0x04, HW_OPTICAL_COM = 0x08, HW_BLUETOOTH_COM = 0x10, HW_DUALCORE = 0x20 }
	Optional features present in the dive computer hardware. More...

enum	HardwareDescriptor { HW_UNKNOWN_OSTC = 0, HW_Frog = HW_BLUETOOTH_COM, HW_OSTCSport_a = HW_LIGHT_SENSOR \| HW_BLUETOOTH_COM, HW_OSTCSport_b = HW_OSTCSport_a \| HW_CHARGEABLE_BATTERY, HW_OSTC2c = HW_CHARGEABLE_BATTERY, HW_OSTC2_a = HW_CHARGEABLE_BATTERY \| HW_BLUETOOTH_COM, HW_OSTC2_b = HW_OSTCSport_b, HW_OSTC2_c = HW_OSTC2_b \| HW_OPTICAL_COM, HW_OSTC3 = HW_LIGHT_SENSOR \| HW_OPTICAL_COM, HW_OSTC3p_a = HW_LIGHT_SENSOR \| HW_OPTICAL_COM \| HW_BLUETOOTH_COM, HW_OSTC3p_b = HW_OSTCSport_b, HW_OSTCcR_a = HW_CHARGEABLE_BATTERY \| HW_S8_COM, HW_OSTCcR_b = HW_OSTCcR_a \| HW_LIGHT_SENSOR, HW_OSTC4 }
	Dive computer set of features. More...

enum	CompanionFeatures { PARAMETERS = (1<<0), DATE = (1<<1), NAME = (1<<2), ICON = (1<<3), DUMPSCREEN = (1<<4), FIRMWARE = (1<<5), HELIUM_DIVE = (1<<6), CCR_DIVE = (1<<7), BLUETOOTH = (1<<8), VPM_MODEL = (1<<9) }
	Features supported by OSTC Companion on the connected device. More...

HardwareDescriptor	hardwareDescriptor ()
	Ask the connect device for its hardware options. More...

virtual CompanionFeatures	supported () const =0
	Tells what is supported for a given computer. More...

virtual QSize	nameSize () const =0
	Length of the custom text displayed by the device. More...

virtual QString	firmwareTemplate () const =0
	filename matching template for compatible firmware. More...

virtual void	loadFirmware (HexFile &, const QString &fileName) const =0
	Read in the specific firmware file format. More...

virtual QRegExp	portTemplate () const =0
	Regular expression to filter USB or Bluetooth port names. More...

High level commands
Commands that implement the specific protocol for a device, to perform all services needed by OSTC Copmanion.
virtual bool	connect ()=0
	Open download mode communication to the dive computer. More...

virtual void	connectServiceMode ()=0
	Open service mode communication to the dive computer. More...

virtual void	writeText (const QString &msg)=0
	Echo a message on the connected device screen. More...

virtual void	setDate (const QDateTime &date)=0
	Set HW dive computer date and time. More...

virtual void	setName (const QString &newName)=0
	Set HW dive computer user text. More...

virtual void	setIcons (const QString &fileName)=0
	Set HW dive computer icon set. More...

virtual QImage	dumpScreen () const =0
	Take a snapshot of the connected computer's screen. More...

virtual void	upgradeFW (const QString &fileName)=0
	Upgrade HW dive computer firmware. More...

virtual bool	disconnect (bool closing=false)=0
	Close connection. More...

Low level protocol
Command and methods that have to be implemented for each device to retrieve device descriptions.
virtual QStringList	listPorts () const =0
	List all communication ports. More...

virtual void	getIdentity ()=0
	Read and check connected dive computer identity. More...

virtual int	firmware () const =0
	The fw's version found during the last getIdentty(). More...

virtual int	serialNumber () const =0
	The serial number found during the last getIdentty(). More...

virtual QString	customText () const =0
	The user-defined string found during the last getIdentty(). More...

virtual QString	description ()=0
	A human readable description of connected computer. More...

static EXPORT unsigned char	retryCommand (Serial &serial, unsigned char cmd, int retries=10)
	Send a command, wait ack, and retry on error. More...

Detailed Description

API for HW dive computer drivers.

This class include high level commands used by the Companion GUI, and other generic services:

List of currently known serial ports: listBluetoothPorts() or listUSBPorts().
Send a command, and wait for the proper acknowledge: retryCommand().

See also: OSTCFrogOperations, OSTC2cOperations, OSTC3Operations,

Member Enumeration Documentation

enum HardwareOperations::CompanionFeatures

Features supported by OSTC Companion on the connected device.

Each driver (instance of this class) is requested to tell Companion what are the supported command.

Enumerator
PARAMETERS	Download/Edit/Upload various parameters.
DATE	Set date & time.
NAME	Set custom text displayed on main screen.
ICON	Set custom image displayed on main screen.
DUMPSCREEN	Makes copy of current screen.
FIRMWARE	Do firmware upgrades.
HELIUM_DIVE	Computes deco stops for trimix dives.
CCR_DIVE	Computes deco stops for rebreather dives.
BLUETOOTH	Use Bluetooh communication (instead of USB)
VPM_MODEL	Also propose VPM deco stops.

enum HardwareOperations::HardwareDescriptor

Dive computer set of features.

Set of features present on a given H&W dive computers.

Note: that several versions exists of a given computer, and there is not a uniq mapping of a given feature set to a dive computer (eg. 0x13 is ambiguous).

Enumerator
HW_UNKNOWN_OSTC
HW_Frog
HW_OSTCSport_a
HW_OSTCSport_b
HW_OSTC2c
HW_OSTC2_a
HW_OSTC2_b
HW_OSTC2_c
HW_OSTC3
HW_OSTC3p_a
HW_OSTC3p_b
HW_OSTCcR_a
HW_OSTCcR_b
HW_OSTC4

enum HardwareOperations::HardwareOption

Optional features present in the dive computer hardware.

8 bit mask. See HardwareDescriptor for known combinations.

Enumerator
HW_CHARGEABLE_BATTERY	Recharge option.
HW_LIGHT_SENSOR	Detects light level, and tune screen.
HW_S8_COM	Analog connector to O2 cells.
HW_OPTICAL_COM	Digital connector to O2 cells.
HW_BLUETOOTH_COM	Bluetooth, hence no USB connection.
HW_DUALCORE	Dual core processor.

Constructor & Destructor Documentation

virtual HardwareOperations::~HardwareOperations ( )

inlinevirtual

mandatory (and empty) virtual descructor in the base class.

Member Function Documentation

virtual bool HardwareOperations::connect ( )

pure virtual

Open download mode communication to the dive computer.

Open comm port, start download mode, check the blessed reply, and get the computer identity (for description() ).

Note: this mode allows common commands to be processed, but not firmware upgrade.

Returns: TRUE is everything went well.

See also: connectServiceMode() and disconnect().

Implemented in OSTC3Operations.

virtual void HardwareOperations::connectServiceMode ( )

pure virtual

Open service mode communication to the dive computer.

Open comm port, start service mode, check the blessed reply.

Note: this mode is mandatory to allow upgradeFW().

Returns: TRUE is everything went well.

See also: connect() and disconnect().

Implemented in OSTC3Operations.

virtual QString HardwareOperations::customText ( ) const

pure virtual

The user-defined string found during the last getIdentty().

See also: getIDentity().

Implemented in OSTC3Operations.

virtual QString HardwareOperations::description ( )

pure virtual

A human readable description of connected computer.

Returns driver name, and identity data found during the last call to getIdentity().

See also: model(), getIntentity()

virtual bool HardwareOperations::disconnect ( bool closing = false )

pure virtual

Close connection.

Exit service mode, and close everything. closing should be set when ending Companion, so an error make a won't crash if the interface is already deleted.

Implemented in OSTC3Operations.

virtual QImage HardwareOperations::dumpScreen ( ) const

pure virtual

Take a snapshot of the connected computer's screen.

Currently only supported by OSTC mk2/2n/2c dive computers.

Implemented in OSTC3Operations.

virtual int HardwareOperations::firmware ( ) const

pure virtual

The fw's version found during the last getIdentty().

See also: getIDentity().

Implemented in OSTC3Operations.

virtual QString HardwareOperations::firmwareTemplate ( ) const

pure virtual

filename matching template for compatible firmware.

Used by the Upgrade Firmware... command to propose only firmwares designed for the connected device.

Implemented in OSTC3Operations.

virtual void HardwareOperations::getIdentity ( )

pure virtual

Read and check connected dive computer identity.

Read fw's version, serial number and custom text from connected computer.

Exceptions

when	the connected device does not matches the driver implementation.

See also: description(), firmware(), serialNumber() and customtext().

Implemented in OSTC3Operations.

HardwareOperations::HardwareDescriptor HardwareOperations::hardwareDescriptor ( )

Ask the connect device for its hardware options.

This is used to guess the device model, even if there is no unicity.

QStringList HardwareOperations::listBluetoothPorts ( ) const

protected

List serial ports for Bluetooth based devices.

Ask OS for the list of Bluetooth serial emulations whose name matches the portTemplate() regular expression.

virtual QStringList HardwareOperations::listPorts ( ) const

pure virtual

List all communication ports.

That are (or might be) used by HW dive computers.

QStringList HardwareOperations::listUSBPorts ( ) const

protected

List serial ports for USB based devices.

Ask OS for the list of USB serial emulation currently connected whose name matches the portTemplate() regular expression.

virtual void HardwareOperations::loadFirmware	(	HexFile &	,
		const QString &	fileName
	)		const

pure virtual

Read in the specific firmware file format.

History is a bit complex here, and the published firmware have different file formats (due to support tool, and/or need for encryption). So each driver have to implement its specific loader.

Implemented in OSTC3Operations.

virtual QString HardwareOperations::model ( ) const

pure virtual

The name of the computer driver.

Returns: the name of a particular driver implementation, eg. "OSTCSport", "OSTC2c", "OSTC3", ...

virtual QSize HardwareOperations::nameSize ( ) const

pure virtual

Length of the custom text displayed by the device.

Returns: (w,h), where w is text width (in chars), and h is the number of lines. Used by Companion GUI to format user input.

Implemented in OSTC3Operations.

virtual QRegExp HardwareOperations::portTemplate ( ) const

pure virtual

Regular expression to filter USB or Bluetooth port names.

Used to propose only the list of ports that matches the serial ports compatible with USB/Bluetooth emulation and the connected dive computer.

unsigned char HardwareOperations::retryCommand	(	Serial &	serial,
		unsigned char	cmd,
		int	retries = `10`
	)

static

Send a command, wait ack, and retry on error.

Service common to all current H&W dive computer: send a command byte, and wait it is dully acknowledged. Allow up to 10x retries when the computer does not answer anything, or reply something else.

Parameters

[in,out]	serial	the connected port to use.
[in]	cmd	command byte to send.
[in]	retries	Optional max number of retries. Default to 10.

Returns: the ack byte (if any), or 0xFF if never received.

Serial& HardwareOperations::serial ( )

inline

Gives access to serial port in use. Used for other high and low level operations, eg. in OSTC Planner.

virtual int HardwareOperations::serialNumber ( ) const

pure virtual

The serial number found during the last getIdentty().

See also: getIDentity().

Implemented in OSTC3Operations.

virtual void HardwareOperations::setDate ( const QDateTime & date )

pure virtual

Set HW dive computer date and time.

Implemented in OSTC3Operations.

virtual void HardwareOperations::setIcons ( const QString & fileName )

pure virtual

Set HW dive computer icon set.

Currently only supported by Frog dive computer.

Implemented in OSTC3Operations.

virtual void HardwareOperations::setName ( const QString & newName )

pure virtual

Set HW dive computer user text.

Implemented in OSTC3Operations.

virtual CompanionFeatures HardwareOperations::supported ( ) const

pure virtual

Tells what is supported for a given computer.

virtual void HardwareOperations::upgradeFW ( const QString & fileName )

pure virtual

Upgrade HW dive computer firmware.

Note: needs service mode connection.

See also: connectServiceMode().

Implemented in OSTC3Operations.

virtual void HardwareOperations::writeText ( const QString & msg )

pure virtual

Echo a message on the connected device screen.

Used on most devices to display commands as they are processed, so the user can see OSTC Companion is working properly, by seeing progress on the dive computer itself.

Implemented in OSTC3Operations.

Member Data Documentation

Serial HardwareOperations::_serial

protected

Communication port used for all I/O operations.

Note that in emulation mode, aka TEST_MODE, this is replaced by an instance of SerialTest.

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

Protected Member Functions

Protected Attributes

Class management

Introspection

High level commands

Low level protocol

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation