host_scripts/README

Overview
-------------

In order to deploy the new touch firmware into the DUT, the corresponding files
would need to be added or modified. In addition, a tarball should be created to
contain all related firmwares and be uploaded into BCS - [1]

[1] https://www.google.com/chromeos/partner/fe/#bcUpload:type=PRIVATE.

Scripts here help users to achieve these works by automatically processing
corresponding files thus users are more easy to complete this change.

Supported Touch Vendors
-----------------------

Atmel, Elan, Melfas and Wacom are supported (more can be supported later).

Phase 1 - Generate the CL
-------------------------

./update_new_firmware_version.sh --action cl ...

User Scenario:
1. Initialize the first version of chromeos-touch-firmware-XXX:
     During the processing cycle, the first version of
     chromeos-touch-firmware-XXX would need to be created and accompany the
     first touch firmware version for a certain touch controller.

2. Support the first touch firmware version of a new touch controller into
     the existed chromeos-touch-firmware-XXX created above.

3. Support the new firmware version for the existed configuration created
     above.

Phase 2 - Update the Manifest after the new tarball is uploaded.
----------------------------------------------------------------

./update_new_firmware_version.sh --action manifest ...

User Scenario:
1. Update the content of Manifest.


Phase 3 - Verify the update result in the DUT
---------------------------------------------

./update_new_firmware_version.sh --action verification ...

User Scenario:
1. To verify the update result by deploying corresponding package into the DUT,
     rebooting the DUT, checking logs in the DUT (via remote ssh connection).

Note: About how to do "cros deploy", please refer to the link [2].

[2] http://www.chromium.org/chromium-os/build/cros-deploy

Phase 4 - Submit CLs to the gerrit for the review process
---------------------------------------------------------

This step is not covered by this script to do automation, the user needs to
operate git commands for submitting CLs into the gerrit.


Examples
--------

* Phase 1 - User Scenario 1

  There is no folder of chromeos-touch-firmware-reef in overlay-reef-private yet
  and the user would like to add first new firmware binary into the image for
  touch_updater in the DUT to update this new firmware.

  What information we need are board name (ex: reef), touch vendor name (ex:
  atmel, elan, melfas ...etc), touch type (ex: TS - touchscreen), product id
  (ex: 100.0), firmware version (ex: 1.0) and file path of firmware binary (ex:
  ./XXX/aaa.bb). Finally the whole command line would be like below:

  ./update_new_firmware_version.sh -a cl --board reef -cpu x86 \
    --touch_vendor XXX --touch_type TS --product_id 100.0 \
    --firmware_version 1.0 --firmware_path ./XXX/aaa.bb

* Phase 1 - User Scenario 2 / 3

  Folder of chromeos-touch-firmware-reef in overlay-reef-private exists already
  and the user would like to add one more new firmware binary or update the
  new revision of firmware binary which is in the ebuild file already.

  What information we need are board name (ex: reef), touch vendor name (ex:
  atmel, elan, melfas ...etc), touch type (ex: TS - touchscreen), product id
  (ex: 101.0), firmware version (ex: 1.0) and file path of firmware binary (ex:
  ./XXX/aaa.bb). Finally the whole command line would be like below:

  ./update_new_firmware_version.sh -a cl --board reef --touch_vendor XXX \
    --touch_type TS --product_id 100.0 --firmware_version 2.0 \
    --firmware_path ./XXX/bb.cc

* Phase 1 - User Scenario 2 / 3 for wacom

  This is the same case as the one above except for the touch vendor is wacom.
  Currently there is no product_id in wacom and we use chassis_id (ex: AAA)
  instead.

  ./update_new_firmware_version.sh -a cl --board reef --touch_vendor wacom \
    --touch_type TS --chassis_id AAA --firmware_version 2.0 \
    --firmware_path ./XXX/bb.cc

* Phase 2

  Once the user uploads new tarball generated by phase 1, the Manifest should be
  updated by the command below:

  ./update_new_firmware_version.sh -a manifest --board XXX

* Phase 3

  Finally the user can also verify the update result by this script. Before
  doing this, the user needs to prepare the environment to perform
  "cros deploy" [2].

  What information we need are board name (ex: reef), touch vendor name (ex:
  atmel, elan, melfas ...etc), firmware_version (ex: 1.0) and the IP address of
  the remote DUT (ex: x.x.x.x). Finally the whole command line would be like
  below:

  ./update_new_firmware_version.sh -a verification --board reef \
    --touch_vendor XXX --firmware_version 1.0 --remote=x.x.x.x

* Phase 4

  There would be messages output by each command line mentioned above then you
  should follow these steps to generate your CLs and post logs to the comment
  of the CL.

  For instance, the possible output message of phase 1 might be

    * Remember to upload the CL for
      /mnt/host/source/src/overlays/overlay-hana/make.conf
    * Remember to copy the console output as a comment to your CL in gerrit.
    * Remember to add changes in chromeos-touch-firmware-hana to a CL
    * Remember to upload this new tarball to BCS
        1. Go to web page -
           https://www.google.com/chromeos/partner/fe/#bcUpload:type=PRIVATE
        2. Select Component File:
           do_not_commit/chromeos-touch-firmware-hana-0.0.1-r4.tbz2
        3. Select Partner: your own partner name
        4. Select Overlay: overlay-hana-private
        5. Relative path to file: chromeos-base/chromeos-touch-firmware-hana
        6. Press "Upload" button
    * After uploading his new tarball to BCS, "./update_new_firmware_version.sh
      -a manifest" should be called to update Manifest file.

  For another case, the output message of phase 3 will ask you to post logs
  generated by this script into the CL for reviewers to check.