View source

[[Category:Gaming]][[Category:Index]](back to [[Will's Notes]].)

I'm currently working on encapsulating all the functionality provided by our specific bike into one class which manages all data and settings and handles all communications with the actual hardware.  I wrote up a little demo app in .NET using Visual C++ that uses this interface.

Here's a recent screenshot:

http://stl.cs.queensu.ca/~cax/screen/twin.png

== Serial Port Library ==

We have optimised the Tunturi interface library to be fast; it uses a Win32 implementation of the pthreads library for threaded asynchronous operation.  Read more about setting up and building pthreads on the [http://dundee.cs.queensu.ca/wiki/index.php/CAX_Dependencies#Input_Library CAX Dependencies page]

=== Doxygen Documentation ===

[http://stl.cs.queensu.ca/~cax/tprot/ The doxygen docs for this library can be found here].

=== Lag Issues ===

From starting to pedal to registration of nonzero speed at the computer's COM port is about 3000 ms; from stopping to pedal until the time when the computer registers zero speed is about 6250 ms.

See [[CAX Game Architecture#User Interaction Tuning|User Interaction Tuning]] for how we are trying to deal with this problem.

=== Serial Port References ===

[http://www.beyondlogic.org/serial/serial.htm Here] is a site that rather thoroughly describes the serial bus used on PCs.

[http://www.eeng.dcu.ie/~scaifer/win2k-dlportio-mingw/DLPORTIOandWIN2KandMinGW32.html This page] contains instructions for getting serial port communication to work under Win NT/2000, etc.  Even has instructions for how to set up the library under MinGW.

[http://www.lvr.com/serport.htm This page] has a large number of links to serial port resources.

My housemate found [http://pyserial.sourceforge.net/ this Python library], which lets you open serial and parallel ports on Windows, *NIX and BSD systems.

[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnfiles/html/msdn_serial.asp This] is Microsoft's Windows SDK reference on serial communications.  Very good.  I used this to hack together my first Win32 COM Port interface in Dev-C++.

=== Old Implementation Notes ===

'''Version 4''': I've reimplemented threading in the Tunturi protocol library behind the top-level object to reduce the latency for reading and writing data off the bike (latency is down to 5-20 ms).  This also makes the main program loop independent of low-level I/O errors that occur relating to the COM port.  Instead of Win32 threads, this time we're using a [http://sources.redhat.com/pthreads-win32/ WinXP port of Posix threads] library.  A (Linux-oriented) tutorial for pthreads is available [http://www.yolinux.com/TUTORIALS/LinuxTutorialPosixThreads.html here].  Version 4 also rips out all the explicit console I/O, replacing this with a configurable logger utility which writes messages to a log file.

'''Version 3''': I cut out the multithreading and reimplemented the COM port library using polling instead.  Data transfer is now down to 15-30ms for a round trip.  I've also put together a small Tunturi protocol library that sits on top and implements all the bike functions that are supported by our hardware.  

'''Version 2''': The COM port library I've been working on over the past few days is progressing well.  I've rewritten the interface to it, and rewritten the Win32 backend, which is now multithreaded with some locking code to protect the input and output buffers.  I've altered the interface so that the com port stream is stored in an object, the way I started writing the library the first time.  This should make it easy to have multiple Tunturi bikes hooked up to the same computer, using a separate COM port for each bicycle.  The largest problem I'm facing right now is the high latency on data transfer: it takes somewhere in the neighbourhood of 1100ms to send a message to the bike and receive a response.  Also, some messages are dropped.  I think I'll take out the multithreading code and reimplement the library using polling to see if I can reduce this.

'''Version 1''': my first attempt at writing a com port library was successful.  The stream object was encapsulated in an object, and the library used polling to do I/O (not multithreaded).

== Tunturi Protocol Fundamentals ==

[http://www.tunturi.com Tunturi]'s bikes all interface to PCs using a serial cable and a proprietary data transmission format (T-protocol).  Data transmission uses standard settings and is performed via a RS232 serial bus (9600bps, 8 bits, no parity, 1 stop bit).

'''el Cinqo de Mayo''': Our new computers didn't have com ports, so I went out and bought an [http://www.startech.com/ststore/itemdetail.cfm?ProductID=PCI1S550&mt=p40 add-in PCI card] with a single serial port on it for my box.  I also hooked the bike up to the PC and confirmed that it's working using the included software.

The T-protocol works by sending messages.  Messages are packaged with a start byte (<tt>0xF1</tt>) and an end byte (<tt>0xF2</tt>).  The first byte inside a message is an opcode that specifies what the message contains; the last byte is always a checksum byte, which is computed by XORing all the other bytes inside the message (not the start or end markers).

Because of the "specialness" of the start and end markers <tt>0xF1</tt> and <tt>0xF2</tt>, the T-protocol defines an escape character, <tt>0xF3</tt> to allow these values to be passed inside a message.  The escape rewrite rules are:

<tt>0xF1 -> 0xF3, 0x01</tt><br>
<tt>0xF2 -> 0xF3, 0x02</tt><br>
<tt>0xF3 -> 0xF3, 0x03</tt>

All rewriting takes place after packaging the data into messages and computing checksums (i.e., escape the characters immediately before writing them to the serial port).

Multibyte data are transmitted in big-endian format (i.e., most-significant byte first).

Several Tunturi functions start with Get- and allow access to data; these messages cause the bike to send back an AnswerAck message, containing the requested data.  Many of these Get-functions have a corresponding Set- message with an opcode one greater, whose internal message layout is an exact copy of the data returned by the Get- message.

For example, the following is a GetUserData message (opcode <tt>0x04</tt>).

''Input:'' <tt>F1 04 04 F2</tt><br>
''Output:'' <tt>F1 04 31 DD 01 02 EB F2</tt>  (''AnswerAck'') 

The corresponding SetUserData (which has an opcode of <tt>0x05</tt>) message would be

<tt>F1 05 31 DD 01 02 EA F2</tt>

Note the changed checksum byte.  Set-messages tend to cause the bike to return a copy of the Set-message as acknowledgement.  The Set-messages supported by the E6R are:

<ul>
<li>SetUserData (5, <tt>0x05</tt>)
<li>SetRemStatus (7, <tt>0x07</tt>)
<li>SetTargetData (9, <tt>0x09</tt>)
</ul>

== Functions Supported by the Tunturi Bicycle ==

I've tested the following functions and know for certain that they are supported on our hardware (Tunturi E6R recumbent exercise bicycle).

=== Controls or Getter-/Setter-Functions ===

{| 
| '''SetReset'''
|  reset the bike controller
|- 
| '''Get-/SetUserData'''
|  retrieve or change the user settings
|- 
| '''Get-/SetRemStatus'''
|  control the remote control status bits
|- 
| '''Get-/SetTargetData'''
|  set the target heartrate or similar
|- 
| '''KeyCmd'''
|  send a software keypress to the bike
|}

=== Data Retrieval Functions ===

{| 
| '''GetCurrentData'''
|  immediate data
|- 
| '''GetCumulatedData'''
|  total trip distance in this session
|- 
| '''GetTotalData'''
|  data since manufacture
|- 
| '''GetSwVersion'''
|  software version
|- 
| '''GetErrorStatus'''
|  ERROR and WARNING status
|}

=== Streaming Data Retrieval Functions ===

{| 
| '''GetCurrentData'''
|  streaming information about bike data
|- 
| '''KeyInfo'''
|  information about keyboard presses on bike
|}

== SerialTTY ==

I've put together a small console program to allow the user to communicate in raw byte format with the Tunturi bicycle controller chip in order to test the protocol and determine which functions are supported by our hardware.  Below is some sample output from this program.

<pre>
Tunturi Protocol debugger
Will Roberts, May 2005

This program allows the user to send an arbitrary byte string
to the Tunturi bicycle using the COM port interface.

Bytes may be space-delimited (e.g. "F1 06 06 f2"), or not
(e.g. "f10606F2").  Case is not important.

Opening COM port ...
Enter input in hexadecimal format (Q to quit): f10202f2
Writing data to COM port ...
< < <   F1 02 02 F2
Reading from COM port ...
> > >   F1 00 02 01 03 F2
Enter input in hexadecimal format (Q to quit): f10a000af2
Writing data to COM port ...
< < <   F1 0A 00 0A F2
Reading from COM port ...
> > >   F1 0A 00 00 00 00 00 0A F2
Enter input in hexadecimal format (Q to quit): q
Closing COM port ...
</pre>

== Supported Functions ==

I'm basically reverse-engineering the Tunturi protocol, going through it function by function and
documenting the response I get and if the function is supported on the
E6R bicycle.  Below, I've listed the functions I've looked at in the bike; mostly, they're query functions, not commands that actually set data or do anything.  Next to each heading I've listed the Tunturi operation code in integer and hex format.  I've just pasted in inputs and outputs verbatim, and I'm working on indicating how these values can be interpreted.

=== SetReset (1, 0x01) ===

''Input:'' <tt>F1 01 01 F2</tt>

''Output:'' No response.

Bike controller and display are instantly reset.

'''This function is fully implemented and tested in [http://stl.cs.queensu.ca/~cax/tprot/classTBicycle.html the TBicycle class].'''

=== GetUserData (4, 0x04) ===

''Input:'' <tt>F1 04 04 F2</tt>

''Output:'' <tt>F1 04 31 DD 01 02 EB F2</tt>  (''AnswerAck'') 

BeatLo is <tt>31</tt> (49=off), <br> 
BeatHi is <tt>DD</tt> (221=off), <br>
sound is <tt>01</tt> (1=on), <br>
units are <tt>02</tt> (2=rpm/miles/kcal/lbs/ft).  

The bike might only support setting the sound and units parameters, or it could allow setting all four of them.

'''This function is not yet implemented in [http://stl.cs.queensu.ca/~cax/tprot/classTBicycle.html the TBicycle class].'''

=== GetRemStatus (6, 0x06) ===

''Input:'' <tt>F1 06 06 F2</tt>

''Output:'' <tt>F1 06 00 00 00 06 F2</tt> (''AnswerAck'')

Control is <tt>00</tt>, <br>
keylock1 is <tt>00</tt>, <br>
keylock2 is <tt>00</tt>

'''This function is not yet implemented in [http://stl.cs.queensu.ca/~cax/tprot/classTBicycle.html the TBicycle class].'''

=== GetTargetData (8, 0x08) ===

''Input:'' <tt>F1 08 08 F2</tt>

''Output:'' <tt>F1 08 00 00 00 00 00 08 F2</tt> (''AnswerAck'')

Mode is <tt>00</tt>, <br>
Target Torque is <tt>00</tt> Nm, <br>
Target Heart Rate is <tt>00</tt> per min, <br>
Target Power Output is <tt>0000</tt> watt.

'''This function is fully implemented and tested in [http://stl.cs.queensu.ca/~cax/tprot/classTBicycle.html the TBicycle class].'''

=== SetTargetData (9, 0x09) ===

This message seems to be the only way of setting the tension on the bicycle, apart from scripting in button-press events (e.g., press <tt>RESET-MANUAL-ENTER-ENTER-UP-UP-UP-UP</tt> or similar).  Button-pressing also has the disadvantage that the bike's current tension cannot be determined, since GetTargetData just returns all zeroes.  The control software would likely get out of synch with the bike fairly quickly.  Unfortunately, the SetTargetData message doesn't seem to give the really fine-level control over bike tension that we want.  Ideally, there would be a command to set the braking tension on the bike, which would take effect immediately.  However, the only way that I've found so far to actually alter tension is using watt control, which operates over a span of several seconds.  I believe this delay is because the bicycle integrated electronics must sample the bike speed and power output before calculating what power to apply to the electric brake.

* Mode = <tt>00</tt> doesn't work, although this is the form of message returned by the bike when the user has entered a program on the console.  The following message has Mode = <tt>00</tt>, Watt = <tt>25</tt>, and resembles the data returned from GetCurrentTarget when the user has chosen one of the first four programs on the bike (the first four are governed by watt control; the last four by heart rate).

 f1 09 00 00 00 00 19 10 f2

* Mode = <tt>01</tt> should set the target torque on the bike, according to the Tprotocol, but it hasn't worked yet.  Torque is supposed to vary from 1 to 32 or 40, but the following message (torque = <tt>25</tt>) has no effect:

 f1 09 01 19 00 00 00 11 f2

* Mode = <tt>02</tt> should set the target heart rate.  As far as I know, this works like watt control, but I haven't been testing it because the heart rate monitor is a bit finicky.  The following sets target heart rate to 140 bpm:

 f1 09 02 00 8c 00 00 87 f2

* Mode = <tt>03</tt> sets target power output in watts.  This works fine, but there is a considerable latency between the time when the tension is change in software and when the bike becomes more difficult to pedal (several full seconds).  Watts may range from 25-400.  This example uses 200:

 f1 09 03 00 00 00 c8 c2 f2

'''This function is implemented and tested (using Watt Control) in the [http://stl.cs.queensu.ca/~cax/tprot/classTBicycle.html TBicycle class].'''

=== GetCurrentData (10, 0x0A) ===

''Input:'' <tt>F1 0A 00 0A F2</tt>  (send once)

''Output:'' <tt>F1 0A 00 00 03 0F 00 06 F2</tt> (''AnswerAck'')

Heart rate is <tt>00</tt> per min, <br>
Power output is <tt>0003</tt> watt, <br>
Speed is <tt>0F</tt> rpm, <br>
keynumber is <tt>00</tt>.

The parameter ''p'' to this message (the byte following opcode <tt>0x0A</tt>) is specified in the Tunturi protocol to make the bike stream current data information.  Messages are supposed to be sent every ''p x 50'' milliseconds.  However, sustained output is not working yet (unknown reason).

''Input:'' <tt>F1 0A 05 0F F2</tt> (send once every 250ms)

''Output:'' <tt>F1 0A 00 00 0A 29 00 29 F2</tt>

The bike sends a single response but then doesn't send anything else.  This can't be a stream error because I/O still works several seconds later, and for now the COM port library is configured to hard fail on any kind of error.

From some work I did with the SerialTTY program this morning, I've put together a list of keynumber values for the bike (these weren't listed in the Tunturi protocol):

<pre>
RESET           = 16  (0x10)
DOWN            = 32  (0x20)
UP              = 48  (0x30)
SCAN HOLD       = 64  (0x40)
MANUAL          = 80  (0x50)
ENTER           = 96  (0x60)
MEMORY          = 112 (0x70)
WATT CONTROL    = 128 (0x80)
PROGRAMS        = 144 (0x90)
TARGET HR       = 160 (0xa0)
</pre>

'''This function is fully implemented and tested in [http://stl.cs.queensu.ca/~cax/tprot/classTBicycle.html the TBicycle class].'''

=== GetCumulatedData (11, 0x0B) ===

''Input:'' <tt>F1 0B 0B F2</tt>

''Output:'' <tt>F1 0B 00 00 00 00 00 00 0A 01 F2</tt> (''AnswerAck'')

Energy expended is <tt>0000</tt> kcal, <br>
Distance travelled is <tt>0000</tt> x 0.1 km, <br>
timehr is <tt>00</tt>, <br>
timemn is <tt>00</tt>, <br>
timesec is <tt>0A</tt>

'''This function is fully implemented and tested in [http://stl.cs.queensu.ca/~cax/tprot/classTBicycle.html the TBicycle class].'''

=== GetTotalData (12, 0x0C) ===

''Input:'' <tt>F1 0C 0C F2</tt>

''Output:'' <tt>F1 0C 00 03 00 03 0C F2</tt> (''AnswerAck'')

Distance is <tt>0003</tt> x km, <br>
time is <tt>0003</tt> x 5 min

'''This function is not yet implemented in [http://stl.cs.queensu.ca/~cax/tprot/classTBicycle.html the TBicycle class].'''

=== KeyCmd (13, 0x0D) ===

''Input:'' <tt>F1 0D 0B 06 F2</tt>

''Output:'' <tt>F1 0D 0B 06 F2</tt> (''NormalAck'')

The bike beeped loudly and the display reset itself.

Thank you, SerialTTY!  The KeyCmd values are slightly different from the ones used in GetCurrentData, and they also aren't documented anywhere in the Tunturi protocol:

<pre>
DOWN            = 2   (0x02)
UP              = 3   (0x03)
SCAN HOLD       = 4   (0x04)
MANUAL          = 5   (0x05)
ENTER           = 6   (0x06)
MEMORY          = 7   (0x07)
WATT CONTROL    = 8   (0x08)
PROGRAMS        = 9   (0x09)
TARGET HR       = 10  (0x0a)
RESET           = 11  (0x0b)
</pre>

'''This function is fully implemented and tested in [http://stl.cs.queensu.ca/~cax/tprot/classTBicycle.html the TBicycle class].'''

=== GetSwVersion (14, 0x0E) ===

''Input:'' <tt>F1 0E 0E F2</tt>

''Output:'' <tt>F1 0E 45 36 20 20 20 20 01 0A 76 F2</tt> (''AnswerAck'')

ID is <tt>453620202020</tt> (<tt>"E6    "</tt>), <br>
version is <tt>01</tt>, <bR>
revision is <tt>0A</tt> (1.10)

'''This function is fully implemented and tested in [http://stl.cs.queensu.ca/~cax/tprot/classTBicycle.html the TBicycle class].'''

=== GetErrorStatus (20, 0x14) ===

''Input:'' <tt>F1 14 14 F2</tt>

''Output:'' <tt>f1 14 00 00 14 f2</tt> (''AnswerAck'')

Error is <tt>00</tt>, <br>
Warning is <tt>00</tt>.

'''This function is not yet implemented in [http://stl.cs.queensu.ca/~cax/tprot/classTBicycle.html the TBicycle class].'''

== Unsupported Functions ==

=== GetCfg (2, 0x02) ===

''Input:'' <tt>F1 02 02 F2</tt>

''Output:'' <tt>F1 00 02 01 03 F2</tt> (''ErrorAck'')

Error code is <tt>01</tt> ('''unsupported command''')

=== GetCalibrationData (16, 0x10) ===

''Input:'' <tt>F1 10 10 F2</tt>

''Output:'' <tt>f1 00 10 01 11 f2</tt> (''ErrorAck'')

Error code <tt>01</tt> indicates '''unsupported function'''.

=== GetSerialNo (18, 0x12) ===

''Input:'' <tt>F1 12 12 F2</tt>

''Output:'' <tt>f1 00 12 01 13 f2</tt> (''ErrorAck'')

Error code <tt>01</tt> indicates '''unsupported function'''.

=== GetClockMode (22, 0x16) ===

''Input:'' <tt>F1 16 16 F2</tt>

''Output:'' <tt>f1 00 16 01 17 f2</tt> (''ErrorAck'')

Error code <tt>01</tt> indicates '''unsupported function'''.

=== GetAllData (24, 0x18) ===

''Input:'' <tt>F1 18 18 F2</tt>

''Output:'' <tt>f1 00 18 01 19 f2</tt> (''ErrorAck'')

Error code <tt>01</tt> indicates '''unsupported function'''.