C5 instructions for Mac

release process/doc updates

Author: emarsman

.travis.yml

@@ -8,7 +8,7 @@ before_install:
 - sudo apt-get update -qq
 - if [ `uname -m` = x86_64 ]; then sudo apt-get install -qq -y libgd2-xpm ia32-libs
   ia32-libs-multiarch; fi
-- script/bootstrap.sh
+- travis_wait script/bootstrap.sh
 - cd src
 after_success:
 - PLATFORM=TESTING make coverage

README.rst

@@ -70,9 +70,6 @@ Releasing
   next development release (one patch release up with the ``-dev`` suffix, e.g.
   ``v0.9.2-dev``
 
-- Also change ``script/bootstrap/pip-requirements.txt`` back to using the development
-  version from Git: ``-e git+https://github.com/openxc/openxc-python.git@next#egg=openxc``
-
 - Go to https://github.com/openxc/vi-firmware/releases and promote the tag you
   just created to a new release - copy and paste the changelog into the
   description.

docs/_static/OpenXC-CrossChasm-Flash.zip

@@ -67,7 +67,7 @@ The Makefile will always print the configuration used so you can double check.
 * :ref:`Mass storage device <msd-storage>` (``MSD_ENABLE`` is ``0``) is disabled 
   by default and is available on certain C5 devices which have a provision to connect 
   a SD card. The time intervals at which the data is logged is 
-  (``DEFAULT_FILE_GENERATE_SECS``is ``180``) set to 180 seconds by default.
+  (``DEFAULT_FILE_GENERATE_SECS`` is ``180``) set to 180 seconds by default.
 
 .. NOTE::
   There's a shortcut for this default build, using the Fabric tool and an
@@ -94,6 +94,7 @@ The Makefile will always print the configuration used so you can double check.
 
   Get the idea? These shortcuts will make sure the flags are set to their
   defaults, regardless of what you may have in your current shell environment.
+  See the fabfile.py or run % fab -l for a complete list of options.
 
 Automatic Recurring OBD-II Requests Build
 ==========================================
@@ -228,7 +229,9 @@ in this case CrossChasm C5 BLE is used as an example:
 .. code-block:: sh
 
   fab c5ble build test_mode_only
-  
+
+.. _fabric-shortcuts:
+
 Fabric Shortcuts
 ================
 
@@ -252,7 +255,14 @@ while this builds the default firmware, ready for OBD2 requests for the chipKIT:
 
 .. code-block:: sh
 
-  fab chipkit build
+  fab chipkit obd2 build
     
-	
+You can specify the message format with ``json``, ``protobuf``, or ``messagepack``:
+
+.. code-block:: sh
+
+  fab reference protobuf build
+
+Other useful options are ``debug``, ``msd_enable``, ``test``, and ``clean``.
+See the fabfile.py or run % fab -l for a complete list of options.
 The ``fab`` commands can be run from any folder in the vi-firmware repository.

docs/_static/QuickStart guide to using C5 Hardware and OpenXC.docx

@@ -15,8 +15,8 @@ These options are passed as shell environment variables to the Makefile, e.g.
 
 .. note::
 
-   Don't miss the ``Fabric`` helper scripts for the :doc:`most common build
-   configurations <example-builds>`.
+   Don't miss the ``Fabric`` helper scripts for the common build configurations in 
+   :ref:`fabric-shortcuts`.
 
 ``PLATFORM``
   Select the target :doc:`microcontroller platform </platforms/platforms>`.

docs/_static/QuickStart guide to using C5 Hardware and OpenXC.pdf

@@ -34,8 +34,7 @@ Flashing a Pre-compiled Firmware
 --------------------------------
 
 Assuming your C5 has the :ref:`bootloader <bootloader>` already flashed, follow
-these :download:`instructions </_static/QuickStart guide to using C5 Hardware and OpenXC.pdf>`
-.. `instructions <http://vi-firmware.openxcplatform.com/en/master/_static/QuickStart%20guide%20to%20using%20C5%20Hardware%20and%20OpenXC.pdf>`_.
+these :download:`instructions </_static/QuickStart guide to using C5 Hardware and OpenXC.pdf>`.
 
 .. _bootloader:
 

docs/compile/example-builds.rst

@@ -37,6 +37,11 @@
     "c5ble": {"name": "CROSSCHASM_C5_BLE", "extension": "hex"}
 }
 
+env.msd_boards = {
+    "c5bt": {"name": "CROSSCHASM_C5_BT", "extension": "hex"},
+    "c5cell": {"name": "CROSSCHASM_C5_CELLULAR", "extension": "hex"},
+}
+
 def latest_git_tag():
     description = local('git describe master', capture=True).rstrip('\n')
     if '-' in description:
@@ -120,11 +125,11 @@ def build_options():
 
     DEFAULT_COMPILER_OPTIONS = {
         'DEBUG': env.debug,
-        'MSD_ENABLE' : 0,
-        'DEFAULT_FILE_GENERATE_SECS' : 180,
+        'MSD_ENABLE' : env.msd_enable,
+        'DEFAULT_FILE_GENERATE_SECS' : env.default_file_generate_secs,
         'BOOTLOADER': env.bootloader,
-        'TEST_MODE_ONLY': 0,
-        'TRANSMITTER': False,
+        'TEST_MODE_ONLY': env.test_mode_only,
+        'TRANSMITTER': env.transmitter,
         'DEFAULT_LOGGING_OUTPUT': env.logging_output,
         'DEFAULT_METRICS_STATUS': False,
         'DEFAULT_CAN_ACK_STATUS': False,
@@ -141,14 +146,8 @@ def build_options():
     }
 
     options = copy.copy(DEFAULT_COMPILER_OPTIONS)
-	
-    options['DEBUG'] = env.debug	
-    options['MSD_ENABLE'] = env.msd_enable
-    options['TEST_MODE_ONLY'] = env.test_mode_only
-    options['DEFAULT_FILE_GENERATE_SECS'] = env.default_file_generate_secs
-    options['BOOTLOADER'] = env.bootloader
-    options['TRANSMITTER'] = env.transmitter
     options['PLATFORM'] = board_options['name']
+
     if env.mode == 'emulator':
         options['DEFAULT_EMULATED_DATA_STATUS'] = True
         options['DEFAULT_POWER_MANAGEMENT'] = "ALWAYS_ON"
@@ -170,6 +169,16 @@ def compile_firmware(build_name, target_path):
                         target_path, build_name, board['name'],
                         env.firmware_release, board['extension']))
 
+        for board_name, board in env.msd_boards.iteritems():
+            msd_enable()
+            env.board = board_name
+            build(capture=True, do_clean=True)
+            local("cp build/%s/vi-firmware-%s.%s %s/vi-%s-firmware-%s-msd-ct%s.%s"
+                    % (board['name'], board['name'], board['extension'],
+                        target_path, build_name, board['name'],
+                        env.firmware_release, board['extension']))
+            env.msd_enable = False #reset
+
 def compress_release(source, archive_path):
     with lcd(os.path.dirname(source)):
         local("zip -r %s %s" % (archive_path, os.path.basename(source)))
@@ -189,7 +198,7 @@ def obd2():
 @task
 def msd_enable():
     if env.board == "c5" or  env.board ==  "c5bt" or env.board == "c5cell":
-        env.msd_enable = True	
+        env.msd_enable = True
     else:
         abort("MSD_ENABLE is only defined for C5_BT or C5_CELL platforms")
 

docs/compile/makefile-opts.rst

@@ -7,51 +7,55 @@ interface firmware in a few common configurations for each supported platform.
 For instructions on how to update your hardware device with one of these files,
 check out the OpenXC website:
 
-http://openxcplatform.com/vehicle-interface/firmware.html
-
-## Emulator Build
+http://openxcplatform.com/vehicle-interface/hardware.html
+
+ ---------------
+| Default Build |
+ ---------------
+
+The files with `default` in the name are compiled for each VI platform with
+these default Makefile options:
+
+        'DEBUG': False,
+        'MSD_ENABLE' : False,
+        'DEFAULT_FILE_GENERATE_SECS' : 180,
+        'BOOTLOADER': True,
+        'TEST_MODE_ONLY': False,
+        'TRANSMITTER': False,
+        'DEFAULT_LOGGING_OUTPUT': "OFF",
+        'DEFAULT_METRICS_STATUS': False,
+        'DEFAULT_CAN_ACK_STATUS': False,
+        'DEFAULT_ALLOW_RAW_WRITE_NETWORK': False,
+        'DEFAULT_ALLOW_RAW_WRITE_UART': False,
+        'DEFAULT_ALLOW_RAW_WRITE_USB': True,
+        'DEFAULT_OUTPUT_FORMAT': "JSON",
+        'DEFAULT_RECURRING_OBD2_REQUESTS_STATUS': False,
+        'DEFAULT_POWER_MANAGEMENT': "SILENT_CAN",
+        'DEFAULT_USB_PRODUCT_ID': 1,
+        'DEFAULT_EMULATED_DATA_STATUS': False,
+        'DEFAULT_OBD2_BUS': 1,
+        'NETWORK': False,
+
+ ----------------
+| Emulator Build |
+ ----------------
 
 The files with `emulator` in the name are compiled for each VI platform with
-these Makefile options:
-
-    'DEBUG': False,
-    'BOOTLOADER': True,
-    'TRANSMITTER': False,
-    'DEFAULT_LOGGING_OUTPUT': "OFF",
-    'DEFAULT_METRICS_STATUS': False,
-    'DEFAULT_CAN_ACK_STATUS': False,
-    'DEFAULT_ALLOW_RAW_WRITE_NETWORK': False,
-    'DEFAULT_ALLOW_RAW_WRITE_UART': False,
-    'DEFAULT_ALLOW_RAW_WRITE_USB': True,
-    'DEFAULT_OUTPUT_FORMAT': "JSON",
-    'DEFAULT_RECURRING_OBD2_REQUESTS_STATUS': False,
-    'DEFAULT_POWER_MANAGEMENT': "ALWAYS_ON",
-    'DEFAULT_USB_PRODUCT_ID': 0x1,
-    'DEFAULT_EMULATED_DATA_STATUS': True,
-    'DEFAULT_OBD2_BUS': 1,
-    'NETWORK': False,
-
-## Translated OBD2 Build
+the following changes from the default Makefile options:
+
+        'DEFAULT_POWER_MANAGEMENT': "ALWAYS_ON",
+        'DEFAULT_EMULATED_DATA_STATUS': True,
+  
+
+ -----------------------
+| Translated OBD2 Build |
+ -----------------------
 
 The files with `translated_obd2` in the name are compiled for each VI platform
-with these Makeflie options:
-
-    'DEBUG': False,
-    'BOOTLOADER': True,
-    'TRANSMITTER': False,
-    'DEFAULT_LOGGING_OUTPUT': "OFF",
-    'DEFAULT_METRICS_STATUS': False,
-    'DEFAULT_CAN_ACK_STATUS': False,
-    'DEFAULT_ALLOW_RAW_WRITE_NETWORK': False,
-    'DEFAULT_ALLOW_RAW_WRITE_UART': False,
-    'DEFAULT_ALLOW_RAW_WRITE_USB': True,
-    'DEFAULT_OUTPUT_FORMAT': "JSON",
-    'DEFAULT_RECURRING_OBD2_REQUESTS_STATUS': True,
-    'DEFAULT_POWER_MANAGEMENT': "OBD2_IGNITION_CHECK",
-    'DEFAULT_USB_PRODUCT_ID': 0x1,
-    'DEFAULT_EMULATED_DATA_STATUS': False,
-    'DEFAULT_OBD2_BUS': 1,
-    'NETWORK': False,
+with the following changes from the default Makefile options:
+
+        'DEFAULT_RECURRING_OBD2_REQUESTS_STATUS': True,
+        'DEFAULT_POWER_MANAGEMENT': "OBD2_IGNITION_CHECK",
 
 This firmware will query the vehicle to see which of a subset of PIDs are
 supported (the list:
@@ -61,34 +65,36 @@ are output as simple vehicle messages, e.g.:
 
     {"name": "engine_speed", "value": 540}
 
-## Default OBD2 Build
-
-The files with `obd2` in the name are compiled for each VI platform with these
-Makeflie options:
-
-    'DEBUG': False,
-    'BOOTLOADER': True,
-    'TRANSMITTER': False,
-    'DEFAULT_LOGGING_OUTPUT': "OFF",
-    'DEFAULT_METRICS_STATUS': False,
-    'DEFAULT_CAN_ACK_STATUS': False,
-    'DEFAULT_ALLOW_RAW_WRITE_NETWORK': False,
-    'DEFAULT_ALLOW_RAW_WRITE_UART': False,
-    'DEFAULT_ALLOW_RAW_WRITE_USB': True,
-    'DEFAULT_OUTPUT_FORMAT': "JSON",
-    'DEFAULT_RECURRING_OBD2_REQUESTS_STATUS': False,
-    'DEFAULT_POWER_MANAGEMENT': "OBD2_IGNITION_CHECK",
-    'DEFAULT_USB_PRODUCT_ID': 0x1,
-    'DEFAULT_EMULATED_DATA_STATUS': False,
-    'DEFAULT_OBD2_BUS': 1,
-    'NETWORK': False,
+ --------------------
+| Default OBD2 Build |
+ --------------------
+
+The files with `obd2` in the name are compiled for each VI platform
+with the following changes from the default Makefile options:
+
+        'DEFAULT_POWER_MANAGEMENT': "OBD2_IGNITION_CHECK",
 
 This firmware is ready to received OBD2 requests over USB or Bluetooth (see the
 message format: https://github.com/openxc/openxc-message-format) but does *not*
 have any pre-defined recurring requests. You probably want this build if you are
 sending your own, custom diagnostic requests.
 
-## License
+ ------------
+| MSD Builds |
+ ------------
+
+For all of the above builds, another similar build is done that enables the SD card
+(Mass Storage Device) for the C5_BT and C5_CELLULAR platforms. All of the files
+have "msd" after the platform in the filename. These are all compiled with the 
+additional Makefile options
+
+        'MSD_ENABLE' : True,
+        'DEFAULT_FILE_GENERATE_SECS' : 180,
+
+
+ ---------
+| License |
+ ---------
 
 These binaries do not contain any closed source components. They are compiled
 soley from the open source OpenXC vehicle interface firmware