P1LOT One - SimHub setup
========================

What is in this archive

  p1lot-update-message.js   The template. You paste its contents into
                            SimHub; you never run it as a file.
  README.txt                This.

It is packed as a .zip because a bare .js arrives from the internet as
something Windows and your antivirus both want to ask about. Unzip it
anywhere, open the .js in Notepad, and copy everything.


Before you start

  SimHub is free and runs on Windows: https://www.simhubdash.com
  Your board is connected by USB and its dashboard is powered.

If the needles have never moved, do the self-test first - unplug USB,
leave the 12 V supply in, hold the button on the board for three
seconds. Both needles sweep. That tells you the hardware is fine
before you go looking for a software problem.

  https://brainiostream.com/products/p1lot-one/setup


Setting it up

1. In SimHub, open "Add/remove features" at the bottom of the left
   menu and enable "Custom serial devices". SimHub restarts.

2. Custom serial devices -> Add new device.

3. Serial port: pick the P1LOT port. Any baud rate works, the board
   ignores it. Tick DTR.

4. Open "Update messages", switch it to "Use javascript", and paste
   the whole of p1lot-update-message.js into the box.

5. Update rate: 10 Hz is enough. 60 Hz is smoother if you have
   SimHub Pro.

6. Start a game. The needles follow it.


Changing what it does

Everything worth adjusting is at the top of the .js, under
USER PARAMETERS, and each one says what it does. The ones people
change first:

  UNITS               0 for km/h and Celsius, 1 for mph and Fahrenheit.
  GEAR_MODE           'A' if the game has a gearbox. 'E' hands the
                      gearbox to the lever for games that model none.
  FORCE_LIGHTS        1 keeps the low-beam telltale lit like a road
                      car. Most race sims have no light switch at all,
                      so the dash sits dark otherwise.
  OIL_PRESSURE_UNIT   'bar' or 'psi', whichever your sim reports.
  BOOST_UNIT          Same.
  LAMP_TEST           true lights every telltale the panel has, all at
                      once. For checking a cluster rather than driving
                      one: what comes up is what your dash carries.
                      Some of them are messages the panel rotates about
                      five seconds each, so give it half a minute
                      before deciding one is missing. Set it back to
                      false afterwards.
  LOW_TYRE_BELOW      Lights the low-pressure lamp under this reading.
                      Off unless you set it, because the units differ
                      between games: read what yours shows at a normal
                      pressure and set this a little under it.

Paste it back into SimHub after you edit it. SimHub keeps its own copy
of the text; the file on disk is only your master.


If it does not work

The needles sweep on the button but the game does nothing
  It is SimHub, not the hardware. Check the port is the P1LOT one,
  DTR is ticked, and the template went into "Update messages" and not
  somewhere else.

Everything stopped and SimHub says nothing
  SimHub disables a formula for 30 seconds after an error. Look at
  the message under the javascript box.

Some things move and others do not
  Not every game reports every signal. A property a game does not have
  reads as nothing and that field simply keeps its last value.

It worked, then stopped
  The board holds the last picture for half a second and shuts the
  dashboard down five seconds after telemetry stops. It wakes on the
  next line. Start the game again.


The port has one owner

Windows gives a COM port to one program at a time. While SimHub holds
it, nothing else can open it - not a terminal, not any other tool.
Disable the device in SimHub first, then reopen it when you are done.


Where the rest is

  Setup walk-through   https://brainiostream.com/products/p1lot-one/setup
  Protocol reference   https://brainiostream.com/products/p1lot-one/developers
  Firmware             https://brainiostream.com/downloads

The wire format this template writes is documented in full on the
developers page, and the .js repeats the field table in its header. If
you want to drive the board from something other than SimHub, that is
all you need - it is plain text on a serial port.
