update docs for new spike bridge

config/spike.rst

@@ -1,7 +1,6 @@
 spike:
 ======
 
-
 *Config file section*
 
 +----------------------------------------------------------------------------+---------+
@@ -10,6 +9,8 @@ spike:
 | Valid in :doc:`mode config files </config/instructions/mode_config>`       | **NO**  |
 +----------------------------------------------------------------------------+---------+
 
+.. overview
+
 The ``spike:`` section of your machine-wide config is where you
 configure hardware options that are specific to the SPIKE interface
 when you're using MPF with a Stern SPIKE machine.
@@ -25,57 +26,112 @@ config file, so be sure to read that if you have a SPIKE machine.
    spike:
       port: /dev/ttyUSB0
       baud: 115200
+      runtime_baud: 3000000
+      flow_control: True
       debug: False
-      nodes: 0, 1, 8, 9, 10, 116
+      nodes: 0, 1, 8, 9, 10, 11
+
 
-Required Settings
+Required settings
 -----------------
 
 The following sections are required in the ``spike:`` section of your config:
 
-port:
-~~~~~
-
-Use the port of your USB-serial adapter or of the internal serial
-on the RPi.
-
 baud:
 ~~~~~
+Single value, type: ``integer``.
 
 This needs to match the value from Step 3 in the MPF SPIKE bridge
 instructions.
 
 nodes:
 ~~~~~~
+List of one (or more) values, each is a type: ``integer``.
 
 Configure the nodes from your manual. Note that there should
 always be a node 0 and 1.
 
-Optional Settings
+port:
+~~~~~
+Single value, type: ``string``.
+
+on the RPi.
+
+
+Optional settings
 -----------------
-The following sections are optional in the ``spike:`` section of your config.
-(If you don't include them, the default will be used).
+
+The following sections are optional in the ``spike:`` section of your config. (If you don't include them, the default will be used).
+
+bridge_debug:
+~~~~~~~~~~~~~
+Single value, type: ``boolean`` (Yes/No or True/False). Default: ``False``
+
+Set to True if you want to debug your MPF Spike bridge.
+
+bridge_debug_log:
+~~~~~~~~~~~~~~~~~
+Single value, type: ``string``. Default: ``/mnt/spike.log``
+
+Path on your Spike system where the bridge logs to if ``bridge_debug`` is ``True``.
+Needs to be writable and sufficiently large.
+A USB stick mounted to ``/mnt/`` will work fine.
+
+bridge_path:
+~~~~~~~~~~~~
+Single value, type: ``string``. Default: ``/bin/bridge``
+
+Path of your bridge.
+
+console_log:
+~~~~~~~~~~~~
+Single value, type: one of the following options: none, basic, full. Default: ``none``
+
+Log level to console.
 
 debug:
 ~~~~~~
+Single value, type: ``boolean`` (Yes/No or True/False). Default: ``False``
 
 Set to true for troubleshooting to print more details in the log.
-Default is ``False``.
+
+file_log:
+~~~~~~~~~
+Single value, type: one of the following options: none, basic, full. Default: ``basic``
+
+Log level to file.
 
 flow_control:
 ~~~~~~~~~~~~~
+Single value, type: ``boolean`` (Yes/No or True/False). Default: ``False``
 
 Set to ``True`` to enable serial RTS/CTS flow control between MPF and the Spike bridge. May
 help improve responsiveness and reduce latency when streaming display data to the DMD.
 Default is ``False``.
 
 poll_hz:
 ~~~~~~~~
+Single value, type: ``integer``. Default: ``1000``
 
 Numeric value of how many times per second MPF will poll the SPIKE
 system to check for switch changes. Default is ``1000``.
 
-connection:
+runtime_baud:
+~~~~~~~~~~~~~
+Single value, type: ``integer``. Default: ``921600``
+
+Baud rate to use during runtime.
+
+use_send_key:
+~~~~~~~~~~~~~
+Single value, type: ``boolean`` (Yes/No or True/False). Default: ``False``
+
+Send some magic commands like Spike does.
+Not needed as far as we know.
+
+wait_times:
 ~~~~~~~~~~~
+One or more sub-entries, each in the format of type: ``int``:``int``.
 
-Default is ``shell``. Currently there are no other options.
+A list of commands and their corresponding wait times on the bus.
+Ususally, you do not have to change this.

hardware/spike/config.rst

@@ -34,8 +34,10 @@ settings:
    spike:
       port: /dev/ttyUSB0
       baud: 115200
+      flow_control: False
       debug: False
       nodes: 0, 1, 8, 9, 10, 11
+      runtime_baud: 115200
 
 Some notes on the settings:
 
@@ -45,9 +47,20 @@ port:
 
 baud:
    This needs to match the value from Step 3 in the
-   :doc:`MPF SPIKE bridge instructions <mpf-spike-bridge>`. Note that since
-   only control and switch information is sent across this bus, 115k baud is
-   plenty fast enough, though it can technically support more.
+   :doc:`MPF SPIKE bridge instructions <mpf-spike-bridge>`.
+   It is used to initialise the connection to SPIKE only.
+   Afterwards, the bridge will switch to ``runtime_baud``.
+
+flow_control:
+   If your hardware supports flow control and you connected "RTS" and "CTS" in
+   the previous steps set this to True. It will make the connection much more
+   stable at higher speeds.
+   It can be ``False`` for a first test.
+
+runtime_baud:
+   Note that since only control and switch information is sent across this bus,
+   115k baud is plenty fast enough if you choose not to use a DMD.
+   However, if you want to use a DMD you need more speed (see below for details).
 
 debug:
    Set this to true for print more details in the log.
@@ -72,6 +85,7 @@ Once you got your game running you can increase the speed using ``runtime_baud``
       port: /dev/ttyUSB0
       baud: 115200
       runtime_baud: 2000000
+      flow_control: True
       debug: False
       nodes: 0, 1, 8, 9, 10, 11
 
@@ -93,3 +107,4 @@ The following baudrate are supported:
 Depending on your hardware setup they might or might not work.
 Most setups communicate reliably up to something beween 1Mbaud and 2.5Mbaud.
 To stream full 30fps to your DMD you need about 2Mbaud.
+You need flow_control at rates higher than about 0.5MBaud.

hardware/spike/connection.rst

@@ -76,6 +76,11 @@ Pins are marked GND, RX, TX. You do not need more than these.
 
 .. todo:: Add a photo and more detailed pinout instructions (:doc:`/about/help_us_to_write_it`).
 
+Unfortunately, this header seems to be missing on some revisions of Spike.
+You can solder it in though.
+However, it does not contain any flow-control pins to it will not work at
+higher baud rates (up to 400k roughly).
+
 
 OPTION 3: Connect using two USB-Serial Adapters
 -----------------------------------------------
@@ -101,6 +106,10 @@ Connect the "RX" (receive) from one to the "TX" (transmit) on the other and vice
 connect the grounds (possible labeled "GND") together. It's probably a good idea to twist the
 wires together to reduce interference, especially if your wires are more than a few inches long.
 
+In addition to above you should also "CTS" to "DTS" and "DTS" to "CTS".
+This will allow you to enable hardware flow control which is essential at
+higher baud rates (up to 3M).
+
 The following diagram illustrates how everything fits together:
 
 .. image:: /hardware/images/spike_usb_to_usb.jpg

hardware/spike/mpf-spike-bridge.rst

@@ -69,6 +69,14 @@ Furthermore, you might want to add this line to allow USB login
 
    USB0:2345:respawn:/sbin/getty 115200 ttyUSB0 -n -l /bin/sh
 
+If your USB to serial adapter has a "RTS" and "CTS" pin or if you are using
+a null-modem cabel you can enable hardware flow control.
+In that case use the following line (notice that we added ``-h``):
+
+::
+
+   USB0:2345:respawn:/sbin/getty 115200 ttyUSB0 -h -n -l /bin/sh
+
 4. Edit /etc/rc2.d/S95game
 --------------------------
 
@@ -89,9 +97,9 @@ Add mpf-spike-bridge to /bin/bridge and mark it as executable.
 
 On Linux this can be done with `chmod +x bridge` from within the folder.
 
-Get the bridge from https://github.com/missionpinball/mpf-spike-bridge
+Get the bridge from https://github.com/missionpinball/mpf-spike
 
-Note that we have a precompiled binary in there (as well as the C source code).
+Note that we have a precompiled binary in there (as well as the Rust source code).
 
 
 .. note:: It might be hard to mark the bridge binary as executable on Windows