MakingPortsAvailable

Why?

You want users of a specific device to be able to very easily flash their devices and benefit from the work you put into the image? Great!

We will hook up your images with phablet-flash for you if you just follow the instructions below.

Prerequisites

  1. Follow our porting guide to produce an image for the device class you're working on.

  2. Set up a page under Touch/Devices/<vendor> using the Touch/Devices/PortTemplate page as a template.

  3. Fill it out as good as you can.
  4. Add it to our list of ports.

Storing the image meta-information

  1. Create a Launchpad team for the port maintainers. Use <vendor>-image-dev (ie. i9100-image-dev) as the name of the team. (Note: if <vendor> includes a _ (underscore), please use a - (dash) instead.)

  2. Make the phablet-ports-admins team owner of your team. You can do that easily at https://launchpad.net/~<vendor>-image-dev/+reassign. We require this, so that we can easily add more port maintainers in case team members get inactive.

  3. Set up Bazaar with Launchpad. (Some will have done this already.)
    1. Register your SSH key in Launchpad: https://launchpad.net/~/+editsshkeys

    2. Run bzr launchpad-login <your LP ID>

  4. Create a bzr branch with all the necessary information.
    1. bzr init <vendor>

    2. cd <vendor>

    3. create manifest.json and put the URL of your image in there. The notation is in JSON formatand it has the following values:

      • Image URLs: You will need to provide URLs to images, which don't require any user interaction for downloading. Just pointing wget or curl at the URL should do the trick. (goo.im or ubuntuone.com for example.)

        • device (mandatory): it points to the image you're providing.

        • ubuntu (optional): the Ubuntu image, by default it's the latest official Ubuntu image.

      • hash (optional): hash sum of the current image.

      • hash_func (optional): either md5 or sha256.

      • revision (optional): provide a revision for the current image. The easiest is to just use an incrementing number.

      • storage (optional): specify where the contents of the .zip are pushed. (The i9100 port makes use of this for example.)

      Something like this could work:

      {
         "device": {
            "uri": "http://goo.im/devs/MaxWallstedt/ubuntu-touch-i9100/current/saucy-preinstalled-armel-i9100.zip",
            "hash": "fdbcaff8c559883497d8598ea077b98b",
            "hash_func": "md5"
         },
         "ubuntu": {
            "uri": "http://cdimage.ubuntu.com/ubuntu-touch-preview/daily-preinstalled/current/saucy-preinstalled-phablet-armhf.zip",
            "hash": "12345678",
            "hash_func": "md5"
         },
         "revision": "42"
      }

      or

      {
          "device": "http://goo.im/devs/MaxWallstedt/ubuntu-touch-i9100/current/saucy-preinstalled-armel-i9100.zip"
          "revision": "42"
      }


Save the file.

  1. vi license and put as much licensing information in there as possible. It's important that users know which blobs/firmware are available under which license.

  2. bzr add license manifest.json

  3. bzr commit -m "initial commit"

  4. bzr push --remember lp:~<vendor>-image-dev/phablet-image-info/<vendor> (ie: lp:~i9100-image-dev/phablet-image-info/i9100, note: if <vendor> includes a _ (underscore), please use a - (dash) instead.)

  1. Run saucy and have phablet-tools installed, now you can check if it actually works.

    1. sudo apt-get install phablet-tools

    2. phablet-flash community --device <vendor>

  2. Ask the Phablet Port Admins to enable your device images in phablet-tools. Simply use this contact form: https://launchpad.net/~phablet-ports-admins/+contactuser

Updating the image

Once you updated the image, you will want to update the manifest again. Perhaps somebody is going to write a script for this in the future, but in general, you will want to do something like below for your image:

  1. Change into your local image meta-data branch.
  2. Run bzr pull to make sure you incorporate changes a team member may have done.

  3. Edit manifest.json and update

    • the device key if the image URL changed,

    • the hash key if you use it,

    • the revision key if you use it.

  4. Run bzr commit -m "update manifest for new image".

  5. Run bzr push.

Debugging issues

Should anything go wrong with the manifest.json file, you're going to find out about it very early on. phablet-flash should let you know about malformed JSON notation and about unknown, missing or broken keys.

If anything during the download or verification steps should fail, you'll find out about it too.

If there's anything wrong after the download and in the process of flashing you might want to

  • get the copy of /cache/recovery/last_log and /cache/recovery/log right after flashing.

  • try to re-run with phablet-flash --debug community --device <vendor> and save the output.

No matter which issue you run into, feel free to talk to us

Please provide as much info as you can.

Touch/MakingPortsAvailable (last edited 2013-08-09 13:46:24 by dholbach)