Skip to content

Commit

Permalink
Update args help and README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
Moshe Shahar committed Jan 5, 2021
1 parent 83689a5 commit 7e4d24e
Show file tree
Hide file tree
Showing 11 changed files with 212 additions and 312 deletions.
131 changes: 15 additions & 116 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -130,24 +130,32 @@ describing the update type.
```yaml
vendor: # One of "domain" or "vendor-id" fields are expected
domain: pelion.com # FW owner domain. Expected to include a dot (".")
# Will be used to generate a vendor UUID
# or
vendor-id: fa6b4a53d5ad5fdfbe9de663e4d41ffe # Valid vendor UUID

device: # One of "model-name" or "class-id" fields are expected
model-name: Smart Slippers # A device model name
vendor-id: fa6b4a53d5ad5fdfbe9de663e4d41ffe # Valid device-class UUID
# Will be used to generate a device-class UUID
# or
class-id: 327c726ac6e54f7a82fbf1d3beda80f0 # Valid device-class UUID

priority: 1 # Update priority as will be passed to authorization callback
# implemented by application on a device side

payload:
url: http://some-url.com/files?id=1234 # File storage URL for devices to
# acquire the FW candidate
file-path: ./my.fw.bin # Update candidate local file - for digest
# calculation & signing
format: raw-binary # one of following:
# raw-binary - for full image update
# arm-patch-stream - for differential update
component: MAIN # [Optional] Component name - only relevant for manifest v3 format.
# raw-binary - for full image update campaigns
# arm-patch-stream - for delta update campaigns

component: MAIN # [Optional] The name of the component to be updated - only relevant for manifest v3 format.
# If omitted "MAIN" component name will be used for updating
# the main application image

sign-image: True # [Optional] Boolean field accepting True/False values - only
# relevant for manifest v3 format.
# When Set to True - 64 Bytes raw signature over the installed
Expand Down Expand Up @@ -286,119 +294,10 @@ manifest tool input configuration.
```shell
$ manifest-tool schema
```
Output:

```json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Manifest-tool input validator",
"description": "This schema is used to validate the input arguments for manifest-tool",
"type": "object",
"required": [
"vendor",
"device",
"priority",
"payload"
],
"properties": {
"vendor": {
"type": "object",
"properties": {
"domain": {
"$ref": "#/definitions/non_empty_string",
"description": "Vendor Domain",
"pattern": "\\w+(\\.\\w+)+"
},
"vendor-id": {
"$ref": "#/definitions/uuid_hex_string",
"description": "Vendor UUID"
},
"custom-data-path": {
"$ref": "#/definitions/non_empty_string",
"description": "Path to custom data file - must be accessible by the manifest-tool"
}
},
"oneOf": [
{"required": ["domain"]},
{"required": ["vendor-id"]}
]
},
"device": {
"type": "object",
"properties": {
"model-name": {
"$ref": "#/definitions/non_empty_string",
"description": "Device model name"
},
"class-id": {
"$ref": "#/definitions/uuid_hex_string",
"description": "Device class UUID"
}
},
"oneOf": [
{"required": ["model-name"]},
{"required": ["class-id"]}
]
},
"priority": {
"description": "Update priority",
"type": "integer"
},
"payload": {
"type": "object",
"required": [
"url",
"format",
"file-path"
],
"properties": {
"format": {
"description": "Payload format type",
"enum": [
"raw-binary",
"arm-patch-stream"
]
},
"url": {
"$ref": "#/definitions/non_empty_string",
"description": "Payload URL in the cloud storage"
},
"file-path": {
"$ref": "#/definitions/non_empty_string",
"description": "Path to payload file - must be accessible by the manifest-tool"
}
}
},
"component": {
"description": "Component name - only relevant for manifest v3",
"$ref": "#/definitions/non_empty_string"
},
"sign-image":{
"description": "Do sign installed image - only relevant for manifest v3. Required for devices with PKI image authentication in bootloader",
"type": "boolean"
}
},
"definitions": {
"non_empty_string": {
"type": "string",
"minLength": 1
},
"uuid_hex_string": {
"type": "string",
"pattern": "[0-9a-fA-F]{32}",
"description": "HEX encoded UUID string"
}
}
}
```

<span class="notes">**Note:** This schema is an example captured for manifest-tool version 2.0. Make sure to execute the `manifest-tool schema` command on your machine to get the up-to-date schema for your installed tool version.</span>

#### `manifest-tool public-key`

Creates a public key file containing a key in uncompressed point format
(X9.62). Provisioning this file to the device enables the device to
verify the manifest signature.
Create a public key file in uncompressed point format. Provisioning this file to the device enables the device to verify the manifest signature.

**Example**

Expand Down Expand Up @@ -464,7 +363,7 @@ Initializes the developer environment:

<span class="notes">**Note 1:** Use the credentials generated by `manifest-dev-tool init` in the development stage only.</span>

<span class="notes"> **Note 2:** You can keep your access key in `.pelion-dev-presets.yaml` file in your home directory root and select it's using `--gw-preset` option.</span>
<span class="notes"> **Note 2:** You can keep your access key in the `.pelion-dev-presets.yaml` file in your home directory and pass it using the `--gw-preset` option.</span>

**Example of `.pelion-dev-presets.yaml`:**
```yaml
Expand All @@ -476,7 +375,7 @@ Initializes the developer environment:
api_key: ak_SOME_OTHER_VERY_SECRET_API_KEY
```

To obtain an access key and API host URL, in Device Management Portal, click **Access Management** > **Access keys** > **New access key**. Limit the access to the `.pelion-dev-presets.yaml` file to your user only.
To obtain an access key and API host URL, in Device Management Portal, click **Access Management** > **Access keys** > **New access key**. Limit access to the `.pelion-dev-presets.yaml` file to your user only.

**Example**

Expand Down
58 changes: 30 additions & 28 deletions manifesttool/delta_tool/delta_tool.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -160,8 +160,8 @@ def generate_delta(

def get_parser():
parser = argparse.ArgumentParser(
description='Tool for generating delta-updates to be used with '
'Pelion-FOTA',
description='Generate delta patch files to be used for '
'delta update campaigns.',
add_help=False
)
required = parser.add_argument_group('required arguments')
Expand All @@ -170,38 +170,38 @@ def get_parser():
required.add_argument(
'-c', '--current-fw',
type=_existing_file_path_factory,
help='Currently installed on device firmware image for delta update '
help='Path to the currently installed firmware image for delta update '
'calculation.',
required=True
)
required.add_argument(
'-n', '--new-fw',
type=_existing_file_path_factory,
help='New firmware image to be installed on device.',
help='Path to the candidate image.',
required=True
)

required.add_argument(
'-o', '--output',
type=Path,
help='Output delta file name.'
'NOTE: Additional configuration file with '
'same name but with \'.yaml\' extension will be generated. '
'Both files are required by the manifest-tool. Only the '
'output file specified by this argument should be uploaded '
'to Pelion storage.',
help='Output delta patch filename. '
'NOTE: The delta tool generates an additional '
'configuration file with the same name but with a \'.yaml\' '
'extension. The manifest tool needs both files, '
'but only this output file must '
'be uploaded to Pelion storage.',
required=True
)

optional.add_argument(
'-b', '--block-size',
type=_block_size_factory,
help='Compression block size to pass to arm-bsdiff engine.'
'Greater block size will provide better compression, but '
'requires more memory on device side.'
' Default is 512. Minimum is 128. '
' NOTE: This value MUST be aligned with network (COAP/HTTP) '
'buffer size used for download',
help='Compression block size algorithm. '
'A greater size provides better '
'compression, but consumes more memory on the device. '
'Default is 512 bytes. Minimum is 128 bytes. '
'NOTE: This value MUST be aligned with the '
'network (COAP/HTTP) buffer size used for download.',
default=512
)

Expand All @@ -211,35 +211,37 @@ def get_parser():
size_group.add_argument(
'-t', '--threshold',
type=int,
choices=range(30, 100, 10),
choices=range(30, 100),
metavar="[30-100]",
default=60,
help='A threshold in percents that will trigger a warning while '
'comparing patch files size to the new FW size.'
help='The ratio of the delta patch size compared to the '
'candidate image size above which to raise an exception. '
'Default is 60.'
)
size_group.add_argument(
'--skip-size-check',
action='store_false',
dest='threshold',
help='Skip size validations after delta update generation.'
help='Skip threshold validations.'
)

optional.add_argument(
'--debug',
action='store_true',
help='Show exception info on error.'
)
optional.add_argument(
'--version',
action='version',
version='Manifest-Tool version {}'.format(__version__)

help='Print exception info upon exiting.'
)

optional.add_argument(
'-h',
'--help',
action='help',
help='show this help message and exit'
help='Show this help message and exit.'
)
optional.add_argument(
'--version',
action='version',
version='Manifest-Tool version {}'.format(__version__),
help='Show program\'s version number and exit.'
)

return parser
Expand Down
Loading

0 comments on commit 7e4d24e

Please sign in to comment.