Mercurial > public > ostc_companion

comparison HardwareOperations.h @ 1:0b3630a29ad8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Initial version based on previous repository. Project was ported to QT6 and in now cmake based.
author Ideenmodellierer <tiefenrauscher@web.de>
date Thu, 27 Nov 2025 18:40:28 +0100
parents
children
comparison
equal deleted inserted replaced
0:76ccd6ce50c0 1:0b3630a29ad8
1 //////////////////////////////////////////////////////////////////////////////
2 /// \file HardwareOperations.h
3 /// \brief API for HW dive computer drivers.
4 /// \author JD Gascuel.
5 /// \sa OSTC3Operations.h
6 ///
7 /// \copyright (c) 2011-2016 JD Gascuel. All rights reserved.
8 /// $Id$
9 //////////////////////////////////////////////////////////////////////////////
10 //
11 // BSD 2-Clause License:
12 //
13 // Redistribution and use in source and binary forms, with or without
14 // modification, are permitted provided that the following conditions
15 // are met:
16 //
17 // 1. Redistributions of source code must retain the above copyright notice,
18 // this list of conditions and the following disclaimer.
19 //
20 // 2. Redistributions in binary form must reproduce the above copyright notice,
21 // this list of conditions and the following disclaimer in the documentation
22 // and/or other materials provided with the distribution.
23 //
24 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
28 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
34 // THE POSSIBILITY OF SUCH DAMAGE.
35 //
36 //////////////////////////////////////////////////////////////////////////////
37 // HISTORY
38 // 2012-09-22 : [jDG] Initial version, made for OSTC Companion.
39 // 2014-07-07 : [jDG] Cleanups for Subsurface google-summer-of-code.
40 // 2014-07-25 : [jDG] BSD 2-clause license.
41 // 2016-07-14 : ÍjDG] Adding codes for hardware variants of OSTC2/3/4.
42
43 #ifndef HARDWARE_OPERATIONS_H
44 #define HARDWARE_OPERATIONS_H
45
46 #include <QDateTime>
47 #include <QImage>
48 #include <QString>
49 #include <QStringList>
50 #include <QSize>
51 #include <QRegularExpression>
52
53 #ifdef TEST_MODE
54 # include "test/SerialTest.h"
55 #else
56 # include "Serial.h"
57 #endif
58
59 class HexFile;
60
61 //////////////////////////////////////////////////////////////////////////////
62 /// \brief API for HW dive computer drivers.
63 ///
64 /// This class include high level commands used by the *Companion* GUI,
65 /// and other generic services:
66 /// - List of currently known serial ports:
67 /// listBluetoothPorts() or listUSBPorts().
68 ///
69 /// - Send a command, and wait for the proper acknowledge: retryCommand().
70 ///
71 /// \sa OSTCFrogOperations, OSTC2cOperations, OSTC3Operations,
72 /// \nosubgrouping
73 class HardwareOperations
74 {
75 protected:
76 #ifdef TEST_MODE
77 /// \brief Fake communication port used for mockup operations.
78 SerialTest _serial;
79 #else
80 /// \brief Communication port used for all I/O operations.
81 ///
82 /// Note that in *emulation mode*, aka TEST_MODE, this is replaced by
83 /// an instance of SerialTest.
84 Serial _serial;
85 #endif
86
87 public:
88 //////////////////////////////////////////////////////////////////////////
89 /// \name Class management
90 /// \{
91 ///
92 /// Managing the hierarchy of driver classes used to handle the various
93 /// existing H&W devices.
94
95 /// \brief mandatory (and empty) virtual descructor in the base class.
96 virtual ~HardwareOperations() {}
97
98 //------------------------------------------------------------------------
99 /// \brief The name of the computer driver.
100 /// \returns the name of a particular driver implementation,
101 /// eg. "OSTCSport", "OSTC2c", "OSTC3", ...
102 virtual QString model() const = 0;
103
104 //------------------------------------------------------------------------
105 /// \brief Gives access to serial port in use.
106 /// Used for other high and low level operations, eg. in *OSTC Planner*.
107 inline Serial& serial() { return _serial; }
108
109 /// \}
110 //////////////////////////////////////////////////////////////////////////
111 /// \name Introspection
112 /// \{
113 ///
114 /// Methods available to ask the connected device what it does support,
115 /// and how to manage it.
116
117 //------------------------------------------------------------------------
118 /// \brief Optional features present in the dive computer hardware.
119 ///
120 /// 8 bit mask. See HardwareDescriptor for known combinations.
121 ///
122 enum HardwareOption {
123 HW_CHARGEABLE_BATTERY= 0x01, ///< Recharge option.
124 HW_LIGHT_SENSOR = 0x02, ///< Detects light level, and tune screen.
125 HW_S8_COM = 0x04, ///< Analog connector to O2 cells.
126 HW_OPTICAL_COM = 0x08, ///< Digital connector to O2 cells.
127 HW_BLUETOOTH_COM = 0x10, ///< Bluetooth, hence no USB connection.
128 HW_DUALCORE = 0x20, ///< Dual core processor.
129 };
130
131 ///-----------------------------------------------------------------------
132 /// \brief Dive computer set of features.
133 ///
134 /// Set of features present on a given H&W dive computers.
135 /// \note that several versions exists of a given computer, and there
136 /// is not a uniq mapping of a given feature set to a dive computer
137 /// (eg. 0x13 is ambiguous).
138 ///
139 enum HardwareDescriptor {
140 HW_UNKNOWN_OSTC = 0,
141 HW_Frog = HW_BLUETOOTH_COM,
142 HW_OSTCSport_a = HW_LIGHT_SENSOR | HW_BLUETOOTH_COM,
143 HW_OSTCSport_b = HW_OSTCSport_a | HW_CHARGEABLE_BATTERY,
144 HW_OSTC2c = HW_CHARGEABLE_BATTERY,
145 HW_OSTC2_a = HW_CHARGEABLE_BATTERY | HW_BLUETOOTH_COM,
146 HW_OSTC2_b = HW_OSTCSport_b,
147 HW_OSTC2_c = HW_OSTC2_b | HW_OPTICAL_COM,
148 HW_OSTC3 = HW_LIGHT_SENSOR | HW_OPTICAL_COM,
149 HW_OSTC3p_a = HW_LIGHT_SENSOR | HW_OPTICAL_COM | HW_BLUETOOTH_COM,
150 HW_OSTC3p_b = HW_OSTCSport_b,
151 HW_OSTCcR_a = HW_CHARGEABLE_BATTERY | HW_S8_COM,
152 HW_OSTCcR_b = HW_OSTCcR_a | HW_LIGHT_SENSOR,
153 HW_OSTC4 = HW_DUALCORE|HW_BLUETOOTH_COM|
154 HW_OPTICAL_COM|HW_LIGHT_SENSOR|HW_CHARGEABLE_BATTERY
155 };
156
157 //------------------------------------------------------------------------
158 /// \brief Ask the connect device for its hardware options.
159 ///
160 /// This is used to guess the device model, even if there is no unicity.
161 HardwareDescriptor hardwareDescriptor();
162
163 //------------------------------------------------------------------------
164 /// \brief Features supported by OSTC Companion on the connected device.
165 ///
166 /// Each driver (instance of this class) is requested to tell *Companion*
167 /// what are the supported command.
168 ///
169 enum CompanionFeatures {
170 PARAMETERS = (1<<0), ///< Download/Edit/Upload various parameters.
171 DATE = (1<<1), ///< Set date & time.
172 NAME = (1<<2), ///< Set custom text displayed on main screen.
173 ICON = (1<<3), ///< Set custom image displayed on main screen.
174 DUMPSCREEN = (1<<4), ///< Makes copy of current screen.
175 FIRMWARE = (1<<5), ///< Do firmware upgrades.
176 HELIUM_DIVE = (1<<6), ///< Computes deco stops for trimix dives.
177 CCR_DIVE = (1<<7), ///< Computes deco stops for rebreather dives.
178 BLUETOOTH = (1<<8), ///< Use Bluetooh communication (instead of USB)
179 VPM_MODEL = (1<<9), ///< Also propose VPM deco stops.
180 SIGNAL_CHECK = (1<<10) ///< Echo signal quality for bluetooth computer
181 };
182
183 /// \brief Tells what is supported for a given computer.
184 virtual CompanionFeatures supported() const = 0;
185
186 //------------------------------------------------------------------------
187 /// \brief Length of the custom text displayed by the device.
188 ///
189 /// \returns (w,h), where \a w is text width (in chars), and \a h is the
190 /// number of lines.
191 /// Used by *Companion* GUI to format user input.
192 virtual QSize nameSize() const = 0;
193
194 //------------------------------------------------------------------------
195 /// \brief filename matching template for compatible firmware.
196 ///
197 /// Used by the *Upgrade Firmware...* command to propose only firmwares
198 /// designed for the connected device.
199 virtual QString firmwareTemplate() const = 0;
200
201 //------------------------------------------------------------------------
202 /// \brief Read in the specific firmware file format.
203 ///
204 /// History is a bit complex here, and the published firmware have
205 /// different file formats (due to support tool, and/or need for
206 /// encryption).
207 /// So each driver have to implement its specific loader.
208 virtual void loadFirmware(HexFile&, const QString& fileName) const = 0;
209
210 //------------------------------------------------------------------------
211 /// \brief Regular expression to filter *USB* or *Bluetooth* port names.
212 ///
213 /// Used to propose only the list of ports that matches the serial ports
214 /// compatible with USB/Bluetooth emulation and the connected dive
215 /// computer.
216 // virtual QRegExp portTemplate() const = 0;
217 virtual QRegularExpression portTemplate() const = 0;
218 /// \}
219 //////////////////////////////////////////////////////////////////////////
220 /// \name High level commands
221 /// \{
222 ///
223 /// Commands that implement the specific protocol for a device, to perform
224 /// all services needed by *OSTC Copmanion*.
225
226 //------------------------------------------------------------------------
227 /// \brief Open download mode communication to the dive computer.
228 ///
229 /// Open comm port, start download mode, check the blessed reply,
230 /// and get the computer identity (for description() ).
231 ///
232 /// \note this mode allows common commands to be processed, but not
233 /// firmware upgrade.
234 ///
235 /// \returns TRUE is everything went well.
236 /// \sa connectServiceMode() and disconnect().
237 virtual bool connect() = 0;
238
239 //------------------------------------------------------------------------
240 /// \brief Open service mode communication to the dive computer.
241 ///
242 /// Open comm port, start service mode, check the blessed reply.
243 /// \note this mode is mandatory to allow upgradeFW().
244 ///
245 /// \returns TRUE is everything went well.
246 /// \sa connect() and disconnect().
247 virtual void connectServiceMode() = 0;
248
249 //------------------------------------------------------------------------
250 /// \brief Echo a message on the connected device screen.
251 ///
252 /// Used on most devices to display commands as they are processed,
253 /// so the user can see *OSTC Companion* is working properly, by seeing
254 /// progress on the dive computer itself.
255 virtual void writeText(const QString& msg) = 0;
256
257 //------------------------------------------------------------------------
258 /// \brief Set HW dive computer date and time.
259 virtual void setDate(const QDateTime& date) = 0;
260
261 //------------------------------------------------------------------------
262 /// \brief Set HW dive computer user text.
263 virtual void setName(const QString& newName) = 0;
264
265 //------------------------------------------------------------------------
266 /// \brief Display signal quality at OSTC.
267 virtual void getSignal() = 0;
268
269 //------------------------------------------------------------------------
270 /// \brief Read all header from OSTC
271 virtual void getAllHeader(unsigned char* pBuffer) = 0;
272
273 //------------------------------------------------------------------------
274 /// \brief Write all header from OSTC
275 virtual void writeAllHeader(unsigned char* pBuffer) = 0;
276
277
278 //------------------------------------------------------------------------
279 /// \brief Read all samples from OSTC
280 virtual void getAllSamples(unsigned char* pBuffer) = 0;
281
282 //------------------------------------------------------------------------
283 /// \brief Write all samples to OSTC
284 virtual void writeAllSamples(unsigned char* pBuffer) = 0;
285
286 //------------------------------------------------------------------------
287 /// \brief Set HW dive computer icon set
288 ///
289 /// *Currently only supported by Frog dive computer*.
290 virtual void setIcons(const QString& fileName) = 0;
291
292 //------------------------------------------------------------------------
293 /// \brief Take a snapshot of the connected computer's screen.
294 ///
295 /// *Currently only supported by OSTC mk2/2n/2c dive computers*.
296 virtual QImage dumpScreen() const = 0;
297
298 //------------------------------------------------------------------------
299 /// \brief Upgrade HW dive computer firmware.
300 ///
301 /// \note needs service mode connection.
302 /// \sa connectServiceMode().
303 virtual void upgradeFW(const QString& fileName) = 0;
304
305 //------------------------------------------------------------------------
306 /// \brief Close connection.
307 ///
308 /// Exit service mode, and close everything.
309 /// \p closing should be set when ending Companion, so
310 /// an error make a won't crash if the interface is already
311 /// deleted.
312 virtual bool disconnect(bool closing = false) = 0;
313
314 /// \}
315 //////////////////////////////////////////////////////////////////////////
316 /// \name Low level protocol
317 /// \{
318 ///
319 /// Command and methods that have to be implemented for each device
320 /// to retrieve device descriptions.
321
322 //------------------------------------------------------------------------
323 /// \brief List all communication ports
324 ///
325 /// That are (or might be) used by HW dive computers.
326 virtual QStringList listPorts() const = 0;
327
328 //------------------------------------------------------------------------
329 /// \brief Send a command, wait ack, and retry on error.
330 ///
331 /// Service common to all current H&W dive computer: send a command byte,
332 /// and wait it is dully acknowledged.
333 /// Allow up to 10x retries when the computer does not answer anything,
334 /// or reply something else.
335 ///
336 /// \param [in,out] serial: the connected port to use.
337 /// \param [in] cmd: command byte to send.
338 /// \param [in] retries: Optional max number of retries. Default to 10.
339 ///
340 /// \returns the ack byte (if any), or 0xFF if never received.
341 static unsigned char retryCommand(Serial& serial,
342 unsigned char cmd,
343 int retries = 10);
344
345 //------------------------------------------------------------------------
346 /// \brief Read and check connected dive computer identity.
347 ///
348 /// Read fw's version, serial number and custom text from connected computer.
349 ///
350 /// \throws when the connected device does not matches the driver
351 /// implementation.
352 ///
353 /// \sa description(), firmware(), serialNumber() and customtext().
354 virtual void getIdentity() = 0;
355
356 //------------------------------------------------------------------------
357 /// \brief The fw's version found during the last getIdentty().
358 /// \sa getIDentity().
359 virtual int firmware() const = 0;
360
361 //------------------------------------------------------------------------
362 /// \brief The serial number found during the last getIdentty().
363 /// \sa getIDentity().
364 virtual int serialNumber() const = 0;
365
366 //------------------------------------------------------------------------
367 /// \brief The user-defined string found during the last getIdentty().
368 /// \sa getIDentity().
369 virtual QString customText() const = 0;
370
371 //------------------------------------------------------------------------
372 /// \brief A human readable description of connected computer.
373 ///
374 /// Returns driver name, and identity data found during the last call to
375 /// getIdentity().
376 ///
377 /// \sa model(), getIntentity()
378 virtual QString description() = 0;
379
380 /// \}
381 //////////////////////////////////////////////////////////////////////////
382
383 protected:
384 //------------------------------------------------------------------------
385 /// \brief List serial ports for *Bluetooth* based devices.
386 ///
387 /// Ask *OS* for the list of *Bluetooth* serial emulations whose name
388 /// matches the portTemplate() regular expression.
389 ///
390 QStringList listBluetoothPorts() const;
391
392 //------------------------------------------------------------------------
393 /// \brief List serial ports for USB based devices.
394 ///
395 /// Ask *OS* for the list of USB serial emulation currently connected whose name
396 /// matches the portTemplate() regular expression.
397 QStringList listUSBPorts() const;
398
399 };
400
401 #endif // COMPUTEROPERATIONS_H