Blame - examples/ota-provider-app/linux/README.md - third_party/github/project-chip/connectedhomeip

| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

18

| -a, --applyUpdateAction \<proceed \| awaitNextAction \| discontinue\> | Value for the Action field in the first ApplyUpdateResponse. For all subsequent responses, the value of proceed will be used. |

19

| -c, --userConsentNeeded | If supplied, value of the UserConsentNeeded field in the QueryImageResponse is set to true. This is only applicable if value of the RequestorCanConsent field in QueryImage Command is true. Otherwise, value of the UserConsentNeeded field is false. |

20

| -f, --filepath \<file path\> | Path to a file containing an OTA image |

Carol Yang

b63d897

2022-04-13 12:02:25 -0700

[diff] [blame]

21

| -i, --imageUri \<uri\> | Value for the ImageURI field in the QueryImageResponse. If none is supplied, a valid URI is generated. |

Carol Yang

d42cf54

2022-04-04 10:53:00 -0700

[diff] [blame]

22

| -o, --otaImageList \<file path\> | Path to a file containing a list of OTA images |

23

| -p, --delayedApplyActionTimeSec \<time in seconds\> | Value for the DelayedActionTime field in the first ApplyUpdateResponse. For all subsequent responses, the value of zero will be used. |

24

| -q, --queryImageStatus \<updateAvailable \| busy \| updateNotAvailable\> | Value for the Status field in the first QueryImageResponse. For all subsequent responses, the value of updateAvailable will be used. |

25

| -t, --delayedQueryActionTimeSec <time> | Value for the DelayedActionTime field in the first QueryImageResponse. For all subsequent responses, the value of zero will be used. |

26

| -u, --userConsentState \<granted \| denied \| deferred\> | The user consent state for the first QueryImageResponse. For all subsequent responses, the value of granted will be used. Note that --queryImageStatus overrides this option.<li> granted: Status field in the first QueryImageResponse is set to updateAvailable <li> denied: Status field in the first QueryImageResponse is set to updateNotAvailable <li> deferred: Status field in the first QueryImageResponse is set to busy |

27

| -x, --ignoreQueryImage \<ignore count\> | The number of times to ignore the QueryImage Command and not send a response |

28

| -y, --ignoreApplyUpdate \<ignore count\> | The number of times to ignore the ApplyUpdate Request and not send a response |

Stefan Bauer-Schwan

1f1986b

2022-05-13 18:15:55 +0200

[diff] [blame]

29

| -P, --pollInterval <milliseconds> | Poll interval for the BDX transfer. |

Trevor Holbrook

a648ef7

2021-08-19 15:24:40 -0700

[diff] [blame]

30

Carol Yang

6380d38

2022-02-10 20:09:59 -0800

[diff] [blame]

31

**Using `--filepath` and `--otaImageList`**

Trevor Holbrook

a648ef7

2021-08-19 15:24:40 -0700

[diff] [blame]

32

Carol Yang

6380d38

2022-02-10 20:09:59 -0800

[diff] [blame]

33

- The two options cannot be supplied together

Carol Yang

bab351f

2022-03-25 19:57:36 -0700

[diff] [blame]

34

- At least one option must be supplied

Carol Yang

6380d38

2022-02-10 20:09:59 -0800

[diff] [blame]

35

- If `--filepath` is supplied, the application will automatically serve that

Carol Yang

bab351f

2022-03-25 19:57:36 -0700

[diff] [blame]

36

file to the OTA Requestor

Carol Yang

6380d38

2022-02-10 20:09:59 -0800

[diff] [blame]

37

- If `--otaImageList` is supplied, the application will parse the JSON file

38

and extract all required data. The most recent/valid software version will

39

be selected and the corresponding OTA file will be sent to the OTA Requestor

Carol Yang

a9bca9b

2022-03-22 15:42:33 -0700

[diff] [blame]

40

- The SoftwareVersion and SoftwareVersionString sent in the QueryImageResponse

41

is derived from the OTA image header. Please note that if the version in the

Carol Yang

bab351f

2022-03-25 19:57:36 -0700

[diff] [blame]

42

`--otaImageList` JSON file does not match that in the image header, the

Carol Yang

a9bca9b

2022-03-22 15:42:33 -0700

[diff] [blame]

43

application will terminate.

Harsha Rajendran

0cd1620

2022-01-27 13:51:35 -0500

[diff] [blame]

44

Carol Yang

6380d38

2022-02-10 20:09:59 -0800

[diff] [blame]

45

An example of the `--otaImageList` file contents:

Harsha Rajendran

0cd1620

2022-01-27 13:51:35 -0500

[diff] [blame]

46

Carol Yang

6380d38

2022-02-10 20:09:59 -0800

[diff] [blame]

47

```

48

{ "foo": 1, // ignored by parser

49

"deviceSoftwareVersionModel":

50

[

Carol Yang

bab351f

2022-03-25 19:57:36 -0700

[diff] [blame]

51

{ "vendorId": 1, "productId": 1, "softwareVersion": 10, "softwareVersionString": "1.0.0", "cDVersionNumber": 18, "softwareVersionValid": true, "minApplicableSoftwareVersion": 0, "maxApplicableSoftwareVersion": 100, "otaURL": "/tmp/ota_v10.bin" },

52

{ "vendorId": 1, "productId": 1, "softwareVersion": 20, "softwareVersionString": "1.0.1", "cDVersionNumber": 18, "softwareVersionValid": false, "minApplicableSoftwareVersion": 0, "maxApplicableSoftwareVersion": 100, "otaURL": "/tmp/ota_v20.bin" },

53

{ "vendorId": 1, "productId": 1, "softwareVersion": 30, "softwareVersionString": "1.0.2", "cDVersionNumber": 18, "softwareVersionValid": true, "minApplicableSoftwareVersion": 0, "maxApplicableSoftwareVersion": 100, "otaURL": "/tmp/ota_v30.bin" },

54

{ "vendorId": 1, "productId": 1, "softwareVersion": 40, "softwareVersionString": "1.1.0", "cDVersionNumber": 18, "softwareVersionValid": true, "minApplicableSoftwareVersion": 0, "maxApplicableSoftwareVersion": 100, "otaURL": "/tmp/ota_v40.bin" },

55

{ "vendorId": 1, "productId": 1, "softwareVersion": 50, "softwareVersionString": "1.1.1", "cDVersionNumber": 18, "softwareVersionValid": false, "minApplicableSoftwareVersion": 0, "maxApplicableSoftwareVersion": 100, "otaURL": "/tmp/ota_v50.bin" }

Carol Yang

6380d38

2022-02-10 20:09:59 -0800

[diff] [blame]

56

]

57

}

58

```

Harsha Rajendran

0cd1620

2022-01-27 13:51:35 -0500

[diff] [blame]

59

Carol Yang

bab351f

2022-03-25 19:57:36 -0700

[diff] [blame]

60

## Software Image Header

61

62

All Matter software images must contain a header as defined in section 11.21.1

63

of the specification. The

64

[ota_image_tool](https://github.com/project-chip/connectedhomeip/blob/master/src/app/ota_image_tool.py)

65

is available for generating the required header on a software image.

66

67

All images supplied to the OTA Provider application (via `--filepath` or

68

`--otaImageList`) must contain the software image header. The OTA Provider

69

application will use the software version specified in the header to set the

70

`SoftwareVersion` field of the QueryImageResponse. For instance, if the image

71

supplied represents an image with software version 2, the tool can be used as

follows:

```

src/app/ota_image_tool.py create -v 0xDEAD -p 0xBEEF -vn 2 -vs "2.0" -da sha256 firmware.bin firmware.ota

```

Please see this

[section](https://github.com/project-chip/connectedhomeip/tree/master/examples/ota-requestor-app/linux#generate-images)

80

for information on building an OTA Requestor application with a specific

81

software version.

82

Carol Yang

c236706

2022-02-23 18:09:32 -0800

[diff] [blame]

83

## Access Control Requirements

84

85

Commissioner or Administrator SHOULD install necessary ACL entries at

86

commissioning time or later to enable processing of QueryImage commands from OTA

87

Requestors on their fabric, otherwise that OTA Provider will not be usable by

88

OTA Requestors.

89

90

Since the ACL attribute contains a list of ACL entries, writing of the attribute

91

should not just contain the values for the new entry. Any existing entries

92

should be read and included as part of the write. Below is an example of how to

93

write the ACL attribute with two entries:

94

95

```

96

out/chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": [{"cluster": 41, "endpoint": null, "deviceType": null}]}]' 0xDEADBEEF 0

97

```

98

99

- Entry 1: This is the original entry created as part of commissioning which

100

grants administer privilege to the node ID 112233 (default controller node

101

ID) for all clusters on every endpoint

102

- Entry 2: This is the new entry being added which grants operate privileges

103