tools: better joystick instructions

tools/joystick/README.md

@@ -1,13 +1,17 @@
 # Joystick
 
-**Hardware needed**: [comma two devkit](https://comma.ai/shop/products/comma-two-devkit), laptop, joystick (optional)
+**Hardware needed**: device running openpilot, laptop, joystick (optional)
 
-With joystickd, you can connect your laptop to your comma device over the network and debug controls using a joystick or keyboard, however a joystick is recommended for more precise control.
+With joystickd, you can connect your laptop to your comma device over the network and debug controls using a joystick or keyboard.
+joystickd uses [inputs](https://pypi.org/project/inputs) which supports many common gamepads and joysticks.
 
-Using a keyboard
----
+## Usage
+
+The car must be off, and openpilot must be offroad before starting `joystickd`.
+
+### Using a keyboard
 
-To get started, ssh into your comma device and start joystickd with the following command:
+SSH into your comma device and start joystickd with the following command:
 
 ```shell
 tools/joystick/joystickd.py --keyboard
@@ -15,22 +19,26 @@ tools/joystick/joystickd.py --keyboard
 
 The available buttons and axes will print showing their key mappings. In general, the WASD keys control gas and brakes and steering torque in 5% increments.
 
-Using a joystick
----
+### Joystick on your comma three
+
+Plug the joystick into your comma three aux USB-C port. Then, SSH into the device and start `joystickd.py`.
+
+### Joystick on your laptop
 
-In order to use a joystick over the network, we need to run joystickd locally from your laptop and have it send `testJoystick` ZMQ packets over the network to the comma device. First connect a compatible joystick to your PC; joystickd uses [inputs](https://pypi.org/project/inputs) which supports many common gamepads and joysticks.
+In order to use a joystick over the network, we need to run joystickd locally from your laptop and have it send `testJoystick` packets over the network to the comma device.
 
-1. Connect your laptop to your comma device's hotspot and open a new ssh shell. Since joystickd is being run on your laptop, we need to write a parameter to let controlsd know to start in joystick debug mode:
+1. Connect a joystick to your PC.
+2. Connect your laptop to your comma device's hotspot and open a new SSH shell. Since joystickd is being run on your laptop, we need to write a parameter to let controlsd know to start in joystick debug mode:
    ```shell
    # on your comma device
    echo -n "1" > /data/params/d/JoystickDebugMode
    ```
-2. Run bridge with your laptop's IP address. This republishes the `testJoystick` packets sent from your laptop so that openpilot can receive them:
+3. Run bridge with your laptop's IP address. This republishes the `testJoystick` packets sent from your laptop so that openpilot can receive them:
    ```shell
    # on your comma device
    cereal/messaging/bridge {LAPTOP_IP} testJoystick
    ```
-3. Finally, start joystickd on your laptop and tell it to publish ZMQ packets over the network:
+4. Start joystickd on your laptop in ZMQ mode.
    ```shell
    # on your laptop
    export ZMQ=1
@@ -38,8 +46,8 @@ In order to use a joystick over the network, we need to run joystickd locally fr
    ```
 
 ---
-Now start your car and openpilot should go into debug mode with an alert on startup! The status of the axes will display on the alert, while button statuses print in the shell.
+Now start your car and openpilot should go into joystick mode with an alert on startup! The status of the axes will display on the alert, while button statuses print in the shell.
 
 Make sure the conditions are met in the panda to allow controls (e.g. cruise control engaged). You can also make a modification to the panda code to always allow controls.
 
-![Imgur](steer.gif)
+![](steer.gif)

tools/joystick/joystickd.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python
+import os
 import argparse
+from inputs import get_gamepad
 
 import cereal.messaging as messaging
 from common.numpy_fast import interp, clip
 from common.params import Params
-from inputs import get_gamepad
 from tools.lib.kbhit import KBHit
 
 
@@ -62,7 +63,7 @@ def joystick_thread(use_keyboard):
   joystick = Keyboard() if use_keyboard else Joystick()
 
   while True:
-    ret = joystick.update()  # processes joystick/key events and handles state of axes
+    ret = joystick.update()
     if ret:
       dat = messaging.new_message('testJoystick')
       dat.testJoystick.axes = [joystick.axes_values[a] for a in joystick.axes_values]
@@ -72,19 +73,24 @@ def joystick_thread(use_keyboard):
 
 
 if __name__ == '__main__':
-  parser = argparse.ArgumentParser(
-    description='Publishes events from your joystick to control your car',
+  parser = argparse.ArgumentParser(description='Publishes events from your joystick to control your car.\n'
+                                               'openpilot must be offroad before starting joysticked.',
                                    formatter_class=argparse.ArgumentDefaultsHelpFormatter)
   parser.add_argument('--keyboard', action='store_true', help='Use your keyboard instead of a joystick')
   args = parser.parse_args()
 
+  if not Params().get_bool("IsOffroad") and "ZMQ" not in os.environ:
+    print("The car must be off before running joystickd.")
+    exit()
+
+  print()
   if args.keyboard:
-    print('\nGas/brake control: `W` and `S` keys\n'
+    print('Gas/brake control: `W` and `S` keys\n'
           'Steering control: `A` and `D` keys')
     print('Buttons:\n'
           '- `R`: Resets axes\n'
           '- `C`: Cancel cruise control')
   else:
-    print('\nUsing joystick, make sure to run bridge on your device if running over the network!')
+    print('Using joystick, make sure to run cereal/messaging/bridge on your device if running over the network!')
 
   joystick_thread(args.keyboard)