diff --git a/.buildinfo b/.buildinfo new file mode 100644 index 000000000000..541fc1ba96d6 --- /dev/null +++ b/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. +config: 672e07c8e9ea26d1c75940f68632e6f3 +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/BUG_REPORT.html b/BUG_REPORT.html new file mode 100644 index 000000000000..71ae311cdf0e --- /dev/null +++ b/BUG_REPORT.html @@ -0,0 +1,850 @@ + + + + + + + + + + + + Reporting bugs — Matter documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + +
+
+
+
+ + + Ctrl+K +
+
+ + + +
+
+ +
+ + + +
+ + + + +
+ +
+
+ + + +
+
+
+
+ + +
+
+ + + + +
+ +
+ + + +
+ +
+
+ +
+
+ +
+ +
+ +
+ + +
+ +
+ +
+ + + + + + + + + + + + + + + + +
+ + +
+ + + + + + + + + + + + + +
+ +
+ +
+
+ + + +
+

Reporting bugs

+ +
+ +
+
+ + + + +
+ +
+

Reporting bugs#

+
+

Writing an effective bug report#

+

When reporting a bug, start with the question +What does a bug report need to tell the developer.

+

Generally you want the following parts covered:

+
    +

  • What is the problem

    • +

  • How can the developer reproduce the problem (to see it for themselves), to +bisect when it was introduced or to find if it got fixed already.

    • +

  • At what point does the problem occur

    • +

  • What environment did this occur in

    • +
+

Make sure the above items are covered and the bug is easy to review and parse:

+
    +

  • Title should clearly describe the problem. Bugs are often sorted from +the issue list which only contains the title

    • +

  • Logs should generally be attachments (drag & drop or click on bottom bar +when entering issue text) and not inline with the issue.

    • +

  • Reproduction steps and environment should be clearly highlighted. If +running commands reproduce the issue (very common), the commands should be +in a code block/script format.

    • +
+
+

Describing the problem#

+

Make sure the issue is obvious or provide a link explaining why the expected +result is not met.

+

Examples:

+
    +

  • (Core dump) seen is obvious since there should be no core dumps

    • +

  • Failure trying to read attribute X in cluster Y which is marked MANDATORY in the spec +references the spec and describes why attribute read should succeed.

    • +

  • Failure trying to write attribute X in cluster Y, which is enabled since cluster FeatureMap enabled X and spec describes as writable. +references the spec and explicitly states that an optional attribute is +enabled based on device status

    • +

  • Running certification test TC-A-B-C (link included) fails at step 3: test case asks for command to succeed, I get ACCESS_DENIED instead +describes a pre-defined test case that is expected to pass but fails. Note +that full link to the test description is needed (and should be covered by +‘how to reproduce’ part)

    • +
+

Unless manually curated (e.g. few lines showing the problem), logs should be +always attachments and not inlined in the bug as the make the bug report too +long.

+
+
+

Reproduction steps and when does the issue occur#

+

Include all steps needed to reproduce the problem. Link any supporting +documentation.

+

If stating something of the form TC-A-B-C step 4 fails then there should be a +link to TC-A-B-C and ideally a list of the commands of each step since test +cases may change over time.

+

The bug report should contain all the information for a developer to reproduce +the issue without needing to have access to CHIP Test case repository (not +everyone does)

+
+
+

Environment for reproduction#

+

Assume that the developer will want to reproduce the issue and will try to +mirror your environment to a reasonable degree. For this, at a minimum the +platforms on which everything is running is needed.

+

Try to provide as much information as seems relevant. At a minimum this could +look like +Failed to commission nrf board using chip-tool running on linux. Used build on SHA abcde.... +This provides basic information (use nrf board, use chip-tool on linux, default +build) to get started. Beyond that, you can refine if more items seem relevant:

+
    +

  • Tested on TE9 or Tested on interop branch xyz gives a build reference +point. Useful when branches/tags are used instead of master branch as +development happens on master branch.

    • +

  • Thread devices fail, tested with qpg and efr32 shows that this seems to be +a general thread issue and developer can investigate on multiple of them

    • +
+
    +

  • Tested with avahi-build and it passes/fails helps the developer with +information of non-default builds that pass/fail to narrow down the problem

    • +

  • Passes with darwin-framework-tool and repl but fails with chip-tool helps +the developer in narrowing down the problem

    • +
+
+
+

Additional information#

+

Providing additional information that can be helpful is encouraged. Each bug +report is different here. Some examples:

+
    +

  • This worked last week (around Jan 5) but started failing in recent master builds

    • +

  • Specification changed this attribute from optional to mandatory so this may be the cause of the issue

    • +

  • This issue may be related to #1234 as the same error is seen, however the reproduction steps seemed distinct enough that I opened a new issue

    • +

  • While running this, I observed 100% CPU before the operation finally timed out

    • +

  • While running this test, I observed device under test rebooting, logs attached.

    • +

  • This only happens intermittently - I see it about 30% of the time

    • +
+
+
+
+ + +
+ + + + + + + + +
+ + + +
+ +
+
+ Contents +
+
+ +
+ + +
+ + + +
+
+
+ + + + + + + + \ No newline at end of file diff --git a/ERROR_CODES.html b/ERROR_CODES.html new file mode 100644 index 000000000000..5f5b2ef36483 --- /dev/null +++ b/ERROR_CODES.html @@ -0,0 +1,1723 @@ + + + + + + + + + + + + Matter SDK CHIP_ERROR enums values — Matter documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + +
+
+
+
+ + + Ctrl+K +
+
+ + + +
+
+ +
+ + + +
+ + + + +
+ +
+
+ + + +
+
+
+
+ + +
+
+ + + + +
+ +
+ + + +
+ +
+
+ +
+
+ +
+ +
+ +
+ + +
+ +
+ +
+ + + + + + + + + + + + + + + + +
+ + +
+ + + + + + + + + + + + + +
+ +
+ +
+
+ + + +
+

Matter SDK CHIP_ERROR enums values

+ +
+ +
+
+ + + + +
+ +
+

Matter SDK CHIP_ERROR enums values#

+

This file was AUTOMATICALLY generated by +python scripts/error_table.py > docs/ERROR_CODES.md. DO NOT EDIT BY HAND!

+
+

Table of contents#

+ +
+
+

SDK Core errors#

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Decimal

Hex

Name

0

0x00

CHIP_NO_ERROR

1

0x01

CHIP_ERROR_SENDING_BLOCKED

2

0x02

CHIP_ERROR_CONNECTION_ABORTED

3

0x03

CHIP_ERROR_INCORRECT_STATE

4

0x04

CHIP_ERROR_MESSAGE_TOO_LONG

5

0x05

CHIP_ERROR_RECURSION_DEPTH_LIMIT

6

0x06

CHIP_ERROR_TOO_MANY_UNSOLICITED_MESSAGE_HANDLERS

7

0x07

CHIP_ERROR_NO_UNSOLICITED_MESSAGE_HANDLER

8

0x08

CHIP_ERROR_NO_CONNECTION_HANDLER

9

0x09

CHIP_ERROR_TOO_MANY_PEER_NODES

10

0x0A

CHIP_ERROR_SENTINEL

11

0x0B

CHIP_ERROR_NO_MEMORY

12

0x0C

CHIP_ERROR_NO_MESSAGE_HANDLER

13

0x0D

CHIP_ERROR_MESSAGE_INCOMPLETE

14

0x0E

CHIP_ERROR_DATA_NOT_ALIGNED

15

0x0F

CHIP_ERROR_UNKNOWN_KEY_TYPE

16

0x10

CHIP_ERROR_KEY_NOT_FOUND

17

0x11

CHIP_ERROR_WRONG_ENCRYPTION_TYPE

18

0x12

CHIP_ERROR_INVALID_UTF8

19

0x13

CHIP_ERROR_INTEGRITY_CHECK_FAILED

20

0x14

CHIP_ERROR_INVALID_SIGNATURE

21

0x15

CHIP_ERROR_INVALID_TLV_CHAR_STRING

22

0x16

CHIP_ERROR_LIT_SUBSCRIBE_INACTIVE_TIMEOUT

23

0x17

CHIP_ERROR_UNSUPPORTED_SIGNATURE_TYPE

24

0x18

CHIP_ERROR_INVALID_MESSAGE_LENGTH

25

0x19

CHIP_ERROR_BUFFER_TOO_SMALL

26

0x1A

CHIP_ERROR_DUPLICATE_KEY_ID

27

0x1B

CHIP_ERROR_WRONG_KEY_TYPE

28

0x1C

CHIP_ERROR_UNINITIALIZED

29

0x1D

CHIP_ERROR_INVALID_IPK

30

0x1E

CHIP_ERROR_INVALID_STRING_LENGTH

31

0x1F

CHIP_ERROR_INVALID_LIST_LENGTH

33

0x21

CHIP_ERROR_END_OF_TLV

34

0x22

CHIP_ERROR_TLV_UNDERRUN

35

0x23

CHIP_ERROR_INVALID_TLV_ELEMENT

36

0x24

CHIP_ERROR_INVALID_TLV_TAG

37

0x25

CHIP_ERROR_UNKNOWN_IMPLICIT_TLV_TAG

38

0x26

CHIP_ERROR_WRONG_TLV_TYPE

39

0x27

CHIP_ERROR_TLV_CONTAINER_OPEN

42

0x2A

CHIP_ERROR_INVALID_MESSAGE_TYPE

43

0x2B

CHIP_ERROR_UNEXPECTED_TLV_ELEMENT

45

0x2D

CHIP_ERROR_NOT_IMPLEMENTED

46

0x2E

CHIP_ERROR_INVALID_ADDRESS

47

0x2F

CHIP_ERROR_INVALID_ARGUMENT

48

0x30

CHIP_ERROR_INVALID_PATH_LIST

49

0x31

CHIP_ERROR_INVALID_DATA_LIST

50

0x32

CHIP_ERROR_TIMEOUT

51

0x33

CHIP_ERROR_INVALID_DEVICE_DESCRIPTOR

56

0x38

CHIP_ERROR_INVALID_PASE_PARAMETER

59

0x3B

CHIP_ERROR_INVALID_USE_OF_SESSION_KEY

60

0x3C

CHIP_ERROR_CONNECTION_CLOSED_UNEXPECTEDLY

61

0x3D

CHIP_ERROR_MISSING_TLV_ELEMENT

62

0x3E

CHIP_ERROR_RANDOM_DATA_UNAVAILABLE

65

0x41

CHIP_ERROR_HOST_PORT_LIST_EMPTY

69

0x45

CHIP_ERROR_FORCED_RESET

70

0x46

CHIP_ERROR_NO_ENDPOINT

71

0x47

CHIP_ERROR_INVALID_DESTINATION_NODE_ID

72

0x48

CHIP_ERROR_NOT_CONNECTED

74

0x4A

CHIP_ERROR_CA_CERT_NOT_FOUND

75

0x4B

CHIP_ERROR_CERT_PATH_LEN_CONSTRAINT_EXCEEDED

76

0x4C

CHIP_ERROR_CERT_PATH_TOO_LONG

77

0x4D

CHIP_ERROR_CERT_USAGE_NOT_ALLOWED

78

0x4E

CHIP_ERROR_CERT_EXPIRED

79

0x4F

CHIP_ERROR_CERT_NOT_VALID_YET

80

0x50

CHIP_ERROR_UNSUPPORTED_CERT_FORMAT

81

0x51

CHIP_ERROR_UNSUPPORTED_ELLIPTIC_CURVE

83

0x53

CHIP_ERROR_CERT_NOT_FOUND

84

0x54

CHIP_ERROR_INVALID_CASE_PARAMETER

86

0x56

CHIP_ERROR_CERT_LOAD_FAILED

87

0x57

CHIP_ERROR_CERT_NOT_TRUSTED

89

0x59

CHIP_ERROR_WRONG_CERT_DN

92

0x5C

CHIP_ERROR_WRONG_NODE_ID

100

0x64

CHIP_ERROR_RETRANS_TABLE_FULL

104

0x68

CHIP_ERROR_TRANSACTION_CANCELED

107

0x6B

CHIP_ERROR_INVALID_SUBSCRIPTION

108

0x6C

CHIP_ERROR_UNSUPPORTED_CHIP_FEATURE

112

0x70

CHIP_ERROR_UNSOLICITED_MSG_NO_ORIGINATOR

113

0x71

CHIP_ERROR_INVALID_FABRIC_INDEX

114

0x72

CHIP_ERROR_TOO_MANY_CONNECTIONS

115

0x73

CHIP_ERROR_SHUT_DOWN

116

0x74

CHIP_ERROR_CANCELLED

118

0x76

CHIP_ERROR_TLV_TAG_NOT_FOUND

119

0x77

CHIP_ERROR_MISSING_SECURE_SESSION

120

0x78

CHIP_ERROR_INVALID_ADMIN_SUBJECT

121

0x79

CHIP_ERROR_INSUFFICIENT_PRIVILEGE

125

0x7D

CHIP_ERROR_MESSAGE_COUNTER_EXHAUSTED

126

0x7E

CHIP_ERROR_FABRIC_EXISTS

127

0x7F

CHIP_ERROR_ENDPOINT_EXISTS

128

0x80

CHIP_ERROR_WRONG_ENCRYPTION_TYPE_FROM_PEER

133

0x85

CHIP_ERROR_INVALID_KEY_ID

134

0x86

CHIP_ERROR_INVALID_TIME

142

0x8E

CHIP_ERROR_SCHEMA_MISMATCH

143

0x8F

CHIP_ERROR_INVALID_INTEGER_VALUE

146

0x92

CHIP_ERROR_BAD_REQUEST

157

0x9D

CHIP_ERROR_WRONG_CERT_TYPE

159

0x9F

CHIP_ERROR_PERSISTED_STORAGE_FAILED

160

0xA0

CHIP_ERROR_PERSISTED_STORAGE_VALUE_NOT_FOUND

161

0xA1

CHIP_ERROR_IM_FABRIC_DELETED

164

0xA4

CHIP_ERROR_IN_PROGRESS

165

0xA5

CHIP_ERROR_ACCESS_DENIED

166

0xA6

CHIP_ERROR_UNKNOWN_RESOURCE_ID

167

0xA7

CHIP_ERROR_VERSION_MISMATCH

171

0xAB

CHIP_ERROR_EVENT_ID_FOUND

172

0xAC

CHIP_ERROR_INTERNAL

173

0xAD

CHIP_ERROR_OPEN_FAILED

174

0xAE

CHIP_ERROR_READ_FAILED

175

0xAF

CHIP_ERROR_WRITE_FAILED

176

0xB0

CHIP_ERROR_DECODE_FAILED

179

0xB3

CHIP_ERROR_DNS_SD_UNAUTHORIZED

180

0xB4

CHIP_ERROR_MDNS_COLLISION

181

0xB5

CHIP_ERROR_IM_MALFORMED_ATTRIBUTE_PATH_IB

182

0xB6

CHIP_ERROR_IM_MALFORMED_EVENT_PATH_IB

185

0xB9

CHIP_ERROR_IM_MALFORMED_COMMAND_DATA_IB

186

0xBA

CHIP_ERROR_IM_MALFORMED_EVENT_DATA_IB

187

0xBB

CHIP_ERROR_MAXIMUM_PATHS_PER_INVOKE_EXCEEDED

188

0xBC

CHIP_ERROR_PEER_NODE_NOT_FOUND

189

0xBD

CHIP_ERROR_HSM

191

0xBF

CHIP_ERROR_REAL_TIME_NOT_SYNCED

192

0xC0

CHIP_ERROR_UNEXPECTED_EVENT

193

0xC1

CHIP_ERROR_ENDPOINT_POOL_FULL

194

0xC2

CHIP_ERROR_INBOUND_MESSAGE_TOO_BIG

195

0xC3

CHIP_ERROR_OUTBOUND_MESSAGE_TOO_BIG

196

0xC4

CHIP_ERROR_DUPLICATE_MESSAGE_RECEIVED

197

0xC5

CHIP_ERROR_INVALID_PUBLIC_KEY

198

0xC6

CHIP_ERROR_FABRIC_MISMATCH_ON_ICA

201

0xC9

CHIP_ERROR_NO_SHARED_TRUSTED_ROOT

202

0xCA

CHIP_ERROR_IM_STATUS_CODE_RECEIVED

215

0xD7

CHIP_ERROR_IM_MALFORMED_DATA_VERSION_FILTER_IB

216

0xD8

CHIP_ERROR_NOT_FOUND

218

0xDA

CHIP_ERROR_INVALID_FILE_IDENTIFIER

219

0xDB

CHIP_ERROR_BUSY

220

0xDC

CHIP_ERROR_MAX_RETRY_EXCEEDED

221

0xDD

CHIP_ERROR_PROVIDER_LIST_EXHAUSTED

223

0xDF

CHIP_ERROR_INVALID_SCHEME_PREFIX

224

0xE0

CHIP_ERROR_MISSING_URI_SEPARATOR

225

0xE1

CHIP_ERROR_HANDLER_NOT_SET

+
+
+

SDK Inet Layer errors#

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Decimal

Hex

Name

257

0x101

INET_ERROR_WRONG_ADDRESS_TYPE

258

0x102

INET_ERROR_PEER_DISCONNECTED

265

0x109

INET_ERROR_HOST_NOT_FOUND

266

0x10A

INET_ERROR_DNS_TRY_AGAIN

267

0x10B

INET_ERROR_DNS_NO_RECOVERY

269

0x10D

INET_ERROR_WRONG_PROTOCOL_TYPE

270

0x10E

INET_ERROR_UNKNOWN_INTERFACE

272

0x110

INET_ERROR_ADDRESS_NOT_FOUND

273

0x111

INET_ERROR_HOST_NAME_TOO_LONG

274

0x112

INET_ERROR_INVALID_HOST_NAME

277

0x115

INET_ERROR_IDLE_TIMEOUT

279

0x117

INET_ERROR_INVALID_IPV6_PKT

280

0x118

INET_ERROR_INTERFACE_INIT_FAILURE

281

0x119

INET_ERROR_TCP_USER_TIMEOUT

282

0x11A

INET_ERROR_TCP_CONNECT_TIMEOUT

283

0x11B

INET_ERROR_INCOMPATIBLE_IP_ADDRESS_TYPE

+
+
+

SDK Device Layer errors#

+ + + + + + + + + + + + + + + + + + + + + + + + + +

Decimal

Hex

Name

513

0x201

CHIP_DEVICE_ERROR_CONFIG_NOT_FOUND

514

0x202

CHIP_DEVICE_ERROR_NOT_SERVICE_PROVISIONED

515

0x203

CHIP_DEVICE_ERROR_SOFTWARE_UPDATE_ABORTED

516

0x204

CHIP_DEVICE_ERROR_SOFTWARE_UPDATE_IGNORED

+
+
+

ASN1 Layer errors#

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Decimal

Hex

Name

768

0x300

ASN1_END

769

0x301

ASN1_ERROR_UNDERRUN

770

0x302

ASN1_ERROR_OVERFLOW

771

0x303

ASN1_ERROR_INVALID_STATE

772

0x304

ASN1_ERROR_MAX_DEPTH_EXCEEDED

773

0x305

ASN1_ERROR_INVALID_ENCODING

774

0x306

ASN1_ERROR_UNSUPPORTED_ENCODING

775

0x307

ASN1_ERROR_TAG_OVERFLOW

776

0x308

ASN1_ERROR_LENGTH_OVERFLOW

777

0x309

ASN1_ERROR_VALUE_OVERFLOW

778

0x30A

ASN1_ERROR_UNKNOWN_OBJECT_ID

+
+
+

BLE Layer errors#

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Decimal

Hex

Name

1025

0x401

BLE_ERROR_ADAPTER_UNAVAILABLE

1027

0x403

BLE_ERROR_NO_CONNECTION_RECEIVED_CALLBACK

1028

0x404

BLE_ERROR_CENTRAL_UNSUBSCRIBED

1029

0x405

BLE_ERROR_GATT_SUBSCRIBE_FAILED

1030

0x406

BLE_ERROR_GATT_UNSUBSCRIBE_FAILED

1031

0x407

BLE_ERROR_GATT_WRITE_FAILED

1032

0x408

BLE_ERROR_GATT_INDICATE_FAILED

1035

0x40B

BLE_ERROR_CHIPOBLE_PROTOCOL_ABORT

1036

0x40C

BLE_ERROR_REMOTE_DEVICE_DISCONNECTED

1037

0x40D

BLE_ERROR_APP_CLOSED_CONNECTION

1039

0x40F

BLE_ERROR_NOT_CHIP_DEVICE

1040

0x410

BLE_ERROR_INCOMPATIBLE_PROTOCOL_VERSIONS

1043

0x413

BLE_ERROR_INVALID_FRAGMENT_SIZE

1044

0x414

BLE_ERROR_START_TIMER_FAILED

1045

0x415

BLE_ERROR_CONNECT_TIMED_OUT

1046

0x416

BLE_ERROR_RECEIVE_TIMED_OUT

1047

0x417

BLE_ERROR_INVALID_MESSAGE

1048

0x418

BLE_ERROR_FRAGMENT_ACK_TIMED_OUT

1049

0x419

BLE_ERROR_KEEP_ALIVE_TIMED_OUT

1050

0x41A

BLE_ERROR_NO_CONNECT_COMPLETE_CALLBACK

1051

0x41B

BLE_ERROR_INVALID_ACK

1052

0x41C

BLE_ERROR_REASSEMBLER_MISSING_DATA

1053

0x41D

BLE_ERROR_INVALID_BTP_HEADER_FLAGS

1054

0x41E

BLE_ERROR_INVALID_BTP_SEQUENCE_NUMBER

1055

0x41F

BLE_ERROR_REASSEMBLER_INCORRECT_STATE

+
+
+

IM Global errors errors#

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Decimal

Hex

Name

1280

0x500

SUCCESS

1281

0x501

FAILURE

1405

0x57D

INVALID_SUBSCRIPTION

1406

0x57E

UNSUPPORTED_ACCESS

1407

0x57F

UNSUPPORTED_ENDPOINT

1408

0x580

INVALID_ACTION

1409

0x581

UNSUPPORTED_COMMAND

1413

0x585

INVALID_COMMAND

1414

0x586

UNSUPPORTED_ATTRIBUTE

1415

0x587

CONSTRAINT_ERROR

1416

0x588

UNSUPPORTED_WRITE

1417

0x589

RESOURCE_EXHAUSTED

1419

0x58B

NOT_FOUND

1420

0x58C

UNREPORTABLE_ATTRIBUTE

1421

0x58D

INVALID_DATA_TYPE

1423

0x58F

UNSUPPORTED_READ

1426

0x592

DATA_VERSION_MISMATCH

1428

0x594

TIMEOUT

1436

0x59C

BUSY

1475

0x5C3

UNSUPPORTED_CLUSTER

1477

0x5C5

NO_UPSTREAM_SUBSCRIPTION

1478

0x5C6

NEEDS_TIMED_INTERACTION

1479

0x5C7

UNSUPPORTED_EVENT

1480

0x5C8

PATHS_EXHAUSTED

1481

0x5C9

TIMED_REQUEST_MISMATCH

1482

0x5CA

FAILSAFE_REQUIRED

1483

0x5CB

INVALID_IN_STATE

1484

0x5CC

NO_COMMAND_RESPONSE

1520

0x5F0

WRITE_IGNORED

+
+
+ + +
+ + + + + + + + +
+ + + +
+ +
+
+ Contents +
+
+ +
+ + +
+ + + +
+
+
+ + + + + + + + \ No newline at end of file diff --git a/PROJECT_FLOW.html b/PROJECT_FLOW.html new file mode 100644 index 000000000000..cce792dd1b88 --- /dev/null +++ b/PROJECT_FLOW.html @@ -0,0 +1,844 @@ + + + + + + + + + + + + Matter Project Flow — Matter documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + +
+
+
+
+ + + Ctrl+K +
+
+ + + +
+
+ +
+ + + +
+ + + + +
+ +
+
+ + + +
+
+
+
+ + +
+
+ + + + +
+ +
+ + + +
+ +
+
+ +
+
+ +
+ +
+ +
+ + +
+ +
+ +
+ + + + + + + + + + + + + + + + +
+ + +
+ + + + + + + + + + + + + +
+ +
+ +
+
+ + + +
+

Matter Project Flow

+ +
+ +
+
+ + + + +
+ +
+

Matter Project Flow#

+

This section is intended to cover how Matter uses GitHub Projects, Issues, +Milestones, Releases, and Branches for program/project management in the code +repository.

+
+

Issues#

+

Matter uses issues as simple problem descriptions or feature requests. In +general, all work contributed to the repository in the form of pull requests +(PR) should be under the auspices of some open issue. This may seem onerous and +in some cases duplicative, so consider these guidelines when deciding whether +you can get away with not creating an issue:

+
    +

  • Trivial fixes: issues can function as TODO lists, simple reminders that +something should be addressed. Sometimes, though, the work required to fix +is smaller than the work required to write the issue.

    • +

  • Issues intended to be addressed by a PR may not actually be fixed or may +regress.

    • +

  • Issues can span PRs (as PRs should be as small as possible, but no smaller).

    • +

  • Issues help form an important basis for release notes. Any PR that addresses +a problem that should have release visibility, please do open an issue.

    • +
+
+
+

Pull requests#

+

Pull requests should be small and address a single, specific change to the code +base. They should be easy to review, as a “yes, that’s better”. Refrain from +requesting review until all PR checks have completed successfully, lest you tire +your reviewers.

+

PR Don’ts:

+
    +

  • Don’t combine unrelated changes. E.g. if the PR addresses a bug in some C +code, an update to the top-level .gitignore doesn’t belong.

    • +

  • Don’t make stacks. E.g. if a change in a component requires a new feature or +even a small tweak in one or more of its dependencies, each dependency +change belongs in its own separate PR.

    • +
+
+
+

Milestones#

+

In Matter parlance, a milestone is simply a tag for an expected due date or +release. Milestones are intended to help contributors and their managers to +prioritize work. There are 2 types: Date-based and Release-based.

+
+

Date-based#

+

Date-based milestones are named for their due date, typically a Friday of some +week. Date-based milestones are normally assigned based on a guess about when +something’s likely to bubble up and get done based on current work load and +resourcing. They are wishes, guesses.

+
+
+

Release-based#

+

Release-based milestones are named for the release version and may have flexible +or subject-to-change due dates. Release-based milestones are intended to track +release blockers.

+

A special “Not sure when” milestone is a marker for issues whose priority, +scope, or blocking status have not been determined. Monthly review of these is a +project goal.

+

Issues without milestones are those that have yet to be considered for one of +the above. Weekly review of new issues is a project goal.

+
+
+
+

Projects#

+

Projects are collections of issues, pull requests, and notes intended to capture +larger efforts that don’t fit in issues, have multiple-subsystems involved, or +may span multiple milestones. We use projects 2 ways:

+
    +

  1. To track burn down on a larger task. When constructing such a project, it’s +important to think in terms of something that will eventually have an end, +i.e. a definite scope.

    2. +

  2. To categorize issues, denote broader efforts without a definite time scope. +These projects might reflect or show burndown or percent complete, but are +mostly used to view where effort is going.

    3. +
+

Issues can belong to any number of projects, but should generally only belong to +one of the task-tracking projects (the first type).

+
+
+

Branches, releases, and general development flow#

+

Master should always be Matter’s best branch. Release branches, once cut, are +closed for any feature work. Software fixes for release branches must first land +on master unless demonstrably infeasible.

+
+
+ + +
+ + + + + + + + +
+ + + +
+ +
+
+ Contents +
+
+ +
+ + +
+ + + +
+
+
+ + + + + + + + \ No newline at end of file diff --git a/QUICK_START.html b/QUICK_START.html new file mode 100644 index 000000000000..6fab83164e12 --- /dev/null +++ b/QUICK_START.html @@ -0,0 +1,842 @@ + + + + + + + + + + + + Quick Start — Matter documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + +
+
+
+
+ + + Ctrl+K +
+
+ + + +
+
+ +
+ + + +
+ + + + +
+ +
+
+ + + +
+
+
+
+ + +
+
+ + + + +
+ +
+ + + +
+ +
+
+ +
+
+ +
+ +
+ +
+ + +
+ +
+ +
+ + + + + + + + + + + + + + + + +
+ + +
+ + + + + + + + + + + + + +
+ +
+ +
+
+ + + +
+

Quick Start

+ +
+ +
+
+ + + + +
+ +
+

Quick Start#

+
+

Demo Overview#

+

The Matter reference implementation contains support for a number of examples +and platforms.

+
+
+

Wi-Fi Nodes#

+ + + + + + + + + + + + + + + + + +

Controller / Admin

Node

Description

chip-tool (Linux / Mac)
Includes docs for all the cluster commands supported

all-clusters-app

  • M5Stack (ESP)
  • Linux simulation

    • Use the command line tool on a laptop to pair with and control an embedded Wi-Fi platform. This demo supports the “all-clusters-app”, so it provides the basic onoff light test and more.

    chip-device-ctrl.py

    all-clusters-app

  • M5Stack (ESP)
  • Linux simulation

    • Same as above, but uses the pychip tool as Controller Node.

    +
    +
    +

    Thread Nodes#

    +

    Use one of the controllers listed above and then a Border Router and Node +combination listed below.

    + + + + + + + + + + + + + + + + + +

    Border Router

    Node

    Description

    ot-br
    Thread Border Router

  • RasPi
  • BeagleBone

    • lighting-app

  • Nordic nRF5x
  • NXP K32W
  • Qorvo QPG6100
  • Silicon Labs EFR32

    • The Lighting example is supported by many of the available Thread platforms. See the chip-tool controller instructions for how to actuate the light on/off cluster.

    ot-br
    Thread Border Router

  • RasPi
  • BeagleBone

    • lock-app

  • Nordic nRF5x
  • NXP K32W
  • Qorvo QPG6100
  • Silicon Labs EFR32
  • TI CC13x2x7

    • The Lock example is supported by many of the available Thread and Wi-Fi platforms.

    +
    +
    +

    Controllers#

    +
    +

    chip-tool#

    +

    This section summarizes how to run some common scenarios with the +chip-tool +controller.

    +
    +

    IP Pairing#

    +

    chip-tool pairing onnetwork ${NODE_ID_TO_ASSIGN} 20202021 will use PASE over +IP to commission a device and assign ${NODE_ID_TO_ASSIGN} (which must be a +decimal number or a 0x-prefixed hex number) as its node id.

    +

    NOTE: On Linux, if the device is actually running after unit tests ran you have +to use chip-tool pairing onnetwork desired-node-id 34567890, because the unit +tests change the device configuration.

    +

    NOTE: to run both the Node and Controller as separate processes on the same +Linux or Mac machine, build the all-clusters-app with Bluetooth LE disabled as +follows:

    +

    scripts/examples/gn_build_example.sh examples/all-clusters-app/linux out/debug/standalone/ chip_config_network_layer_ble=false

    +
    +
    +

    Automated CASE tests#

    +

    chip-tool tests Test_TC_OO_1_1 will run a suite of tests that use CASE To +communicate with a paired all-clusters-app peer node.

    +
    +
    +
    +
    + + +
    + + + + + + + + +
    + + + +
    + +
    +
    + Contents +
    +
    + +
    + + +
    + + + +
    +
    +
    + + + + + + + + \ No newline at end of file diff --git a/README.html b/README.html new file mode 100644 index 000000000000..97d39aa4bae4 --- /dev/null +++ b/README.html @@ -0,0 +1,1001 @@ + + + + + + + + + + + + Matter — Matter documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + + + + + + + + + +
    +
    +
    +
    + + + Ctrl+K +
    +
    + + + +
    +
    + +
    + + + +
    + + + + +
    + +
    +
    + + + +
    +
    +
    +
    + + +
    +
    + + + + +
    + +
    + + + +
    + +
    +
    + +
    +
    + +
    + +
    + +
    + + +
    + +
    + +
    + + + + + + + + + + + + + + + + +
    + + +
    + + + + + + + + + + + + + +
    + +
    + +
    +
    + + + +
    +

    Matter

    + +
    + +
    +
    + + + + +
    + +
    +

    Matter#

    +

    Builds

    +

    Builds

    +

    Android +Ameba +ASR +BouffaloLab +Darwin +TI CC26X2X7 +TI CC32XX +EFR32 +ESP32 +Infineon +i.MX Linux +K32W with SE051 +Linux ARM +Linux Standalone +Linux Standalone +Mbed OS +MW320 +nRF Connect SDK +Open IoT SDK +QPG +STM32 +Telink +Tizen

    +

    Tests

    +

    Unit / Integration Tests +Cirque +QEMU

    +

    Tools

    +

    ZAP Templates

    +

    Documentation

    +

    Documentation Build

    + +
    +
    +

    About#

    +

    Matter (formerly Project CHIP) creates more connections between more objects, +simplifying development for manufacturers and increasing compatibility for +consumers, guided by the Connectivity Standards Alliance.

    +
    +
    +

    What is Matter?#

    +

    Matter is a unified, open-source application-layer connectivity standard built +to enable developers and device manufacturers to connect and build reliable, and +secure ecosystems and increase compatibility among connected home devices. It is +built with market-proven technologies using Internet Protocol (IP) and is +compatible with Thread and Wi-Fi network transports. Matter was developed by a +Working Group within the Connectivity Standards Alliance (Alliance). This +Working Group develops and promotes the adoption of the Matter standard, a +royalty-free connectivity standard to increase compatibility among smart home +products, with security as a fundamental design tenet. The vision that led major +industry players to come together to build Matter is that smart connectivity +should be simple, reliable, and interoperable.

    +

    Matter simplifies development for manufacturers and increases compatibility for +consumers.

    +

    The standard was built around a shared belief that smart home devices should be +secure, reliable, and seamless to use. By building upon Internet Protocol (IP), +Matter enables communication across smart home devices, mobile apps, and cloud +services and defines a specific set of IP-based networking technologies for +device certification.

    +

    The Matter specification details everything necessary to implement a Matter +application and transport layer stack. It is intended to be used by implementers +as a complete specification.

    +

    The Alliance officially opened the Matter Working Group on January 17, 2020, and +the specification is +available +for adoption now.

    +

    Visit buildwithmatter.com to learn more and read +the latest news and updates about the project.

    +
    +
    +

    Project Overview#

    +
    +

    Development Goals#

    +

    Matter is developed with the following goals and principles in mind:

    +

    Unifying: Matter is built with and on top of market-tested, existing +technologies.

    +

    Interoperable: The specification permits communication between any +Matter-certified device, subject to users’ permission.

    +

    Secure: The specification leverages modern security practices and protocols.

    +

    User Control: The end user controls authorization for interaction with +devices.

    +

    Federated: No single entity serves as a throttle or a single point of +failure for root of trust.

    +

    Robust: The set of protocols specifies a complete lifecycle of a device — +starting with the seamless out-of-box experience, through operational protocols, +to device and system management specifications required for proper function in +the presence of change.

    +

    Low Overhead: The protocols are practically implementable on low +compute-resource devices, such as MCUs.

    +

    Pervasive: The protocols are broadly deployable and accessible, by +leveraging IP and being implementable on low-capability devices.

    +

    Ecosystem-Flexible: The protocol is flexible enough to accommodate +deployment in ecosystems with differing policies.

    +

    Easy to Use: The protocol provides smooth, cohesive, integrated provisioning +and out-of-box experience.

    +

    Open: The Project’s design and technical processes are open and transparent +to the general public, including non-members wherever possible.

    +
    +
    +

    Architecture Overview#

    +

    Matter aims to build a universal IPv6-based communication protocol for smart +home devices. The protocol defines the application layer that will be deployed +on devices and the different link layers to help maintain interoperability. The +following diagram illustrates the normal operational mode of the stack: +Matter Architecture Overview

    +

    The architecture is divided into layers to help separate the different +responsibilities and introduce a good level of encapsulation among the various +pieces of the protocol stack. The vast majority of interactions flow through the +stack captured in the following Figure:

    +

    Matter Stack Architecture

    +
      +

    1. Application: High-order business logic of a device. For example, an +application that is focused on lighting might contain logic to handle turning +on/off the bulb as well as its color characteristics.

      2. +
    +
      +

    1. Data Model: The data layer corresponds to the data and verb elements that +help support the functionality of the application. The Application operates +on these data structures when there is an intent to interact with the device.

      2. +
    +
      +

    1. Interaction Model: The Interaction Model layer defines a set of +interactions that can be performed between a client and server device. For +example, reading or writing attributes on a server device would correspond to +application behavior on the device. These interactions operate on the +elements defined at the data model layer.

      2. +
    +
      +

    1. Action Framing: Once an action is constructed using the Interaction +Model, it is serialized into a prescribed packed binary format to encode for +network transmission.

      2. +
    +
      +

    1. Security: An encoded action frame is then sent down to the Security Layer +to encrypt and sign the payload to ensure that data is secured and +authenticated by both sender and receiver of a packet.

      2. +

    2. Message Framing & Routing: With an interaction encrypted and signed, the +Message Layer constructs the payload format with required and optional header +fields; which specify the message’s properties and some routing information.

      3. +
    +
      +

    1. IP Framing & Transport Management: After the final payload has been +constructed, it is sent to the underlying transport protocol for IP +management of the data.

      2. +
    +
    +
    +
    +

    Current Status of Matter#

    +

    Matter’s design and technical processes are intended to be open and transparent +to the general public, including to Working Group non-members wherever possible. +The availability of this GitHub repository and its source code under an Apache +v2 license is an important and demonstrable step to achieving this commitment. +Matter endeavors to bring together the best aspects of market-tested +technologies and redeploy them as a unified and cohesive whole-system solution. +The overall goal of this approach is to bring the benefits of Matter to +consumers and manufacturers as quickly as possible. As a result, what you +observe in this repository is an implementation-first approach to the technical +specification, vetting integrations in practice. The Matter repository is +growing and evolving to implement the overall architecture. The repository +currently contains the security foundations, message framing and dispatch, and +an implementation of the interaction model and data model. The code examples +show simple interactions, and are supported on multiple transports – Wi-Fi and +Thread – starting with resource-constrained (i.e., memory, processing) silicon +platforms to help ensure Matter’s scalability.

    +
    +
    +

    How to Contribute#

    +

    We welcome your contributions to Matter. Read our contribution guidelines +here.

    +
    +
    +

    Building and Developing in Matter#

    +

    Instructions about how to build Matter can be found here .

    +
    +
    +

    Directory Structure#

    +

    The Matter repository is structured as follows:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

    File/Folder

    Content

    build

    Build system support content and built output directories

    build_overrides

    Build system parameter customization for different platforms

    config

    Project configurations

    credentials

    Development and test credentials

    docs

    Documentation, including guides. Visit the Matter SDK documentation page to read it.

    examples

    Example firmware applications that demonstrate use of Matter

    integrations

    3rd party integrations

    scripts

    Scripts needed to work with the Matter repository

    src

    Implementation of Matter

    third_party

    3rd party code used by Matter

    zzz_generated

    ZAP generated template code - Revolving around cluster information

    BUILD.gn

    Build file for the GN build system

    CODE_OF_CONDUCT.md

    Code of conduct for Matter and contribution to it

    CONTRIBUTING.md

    Guidelines for contributing to Matter

    LICENSE

    Matter license file

    REVIEWERS.md

    PR reviewers

    gn_build.sh

    Build script for specific projects such as Android, EFR32, etc.

    README.md

    This file

    +
    +
    +

    License#

    +

    Matter is released under the Apache 2.0 license.

    +
    + + +
    + + + + + + +
    + +
    +
    +
    + +
    + + + +
    + +
    +
    + Contents +
    +
    + +
    + + +
    + + + +
    +
    +
    + + + + + + + + \ No newline at end of file diff --git a/VSCODE_DEVELOPMENT.html b/VSCODE_DEVELOPMENT.html new file mode 100644 index 000000000000..af1732d66f9f --- /dev/null +++ b/VSCODE_DEVELOPMENT.html @@ -0,0 +1,946 @@ + + + + + + + + + + + + Visual Studio Code Development — Matter documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + + + + + + + + + +
    +
    +
    +
    + + + Ctrl+K +
    +
    + + + +
    +
    + +
    + + + +
    + + + + +
    + +
    +
    + + + +
    +
    +
    +
    + + +
    +
    + + + + +
    + +
    + + + +
    + +
    +
    + +
    +
    + +
    + +
    + +
    + + +
    + +
    + +
    + + + + + + + + + + + + + + + + +
    + + +
    + + + + + + + + + + + + + +
    + +
    + +
    +
    + + + +
    +

    Visual Studio Code Development

    + +
    + +
    +
    + + + + +
    + +
    +

    Visual Studio Code Development#

    +

    Visual Studio Code is a great and simple IDE +that can be used to build & develop with for Matter.

    +

    Matter supports the docker / remote container workflow in Visual Studio Code, +and has a container environment setup automatically. You can read more about +this workflow here.

    +

    Tested on:

    +
      +

    • macOS 10.5

      • +

    • Windows 10 Pro + WSL + Ubuntu 18 LTS

      • +

    • Linux - Fedora Core 35 distribution

      • +
    +
    +

    Setup Steps#

    +
      +

    1. Windows Only Enable the Windows Subsystem for Linux (WSL) following +instructions here: +https://docs.microsoft.com/en-us/windows/wsl/install-win10

      2. +

    2. Windows Only Install Ubuntu from the Windows App Store here: +https://www.microsoft.com/en-us/p/ubuntu-1804-lts/9n9tngvndl3q

      3. +

    3. Install Docker for your operating system of choice +from here: https://docs.docker.com/engine/install

      4. +

    4. Install Visual Studio Code for your +operating system of choice here: https://code.visualstudio.com/Download

      5. +

    5. Install Git if you haven’t already

      6. +

    6. Windows Only Enable git to use LF instead of CLRF by default: +git config --global core.autocrlf false

      7. +

    7. Git clone the main Matter repository here: +project-chip/connectedhomeip

      8. +

    8. Launch Visual Studio Code, and open the cloned folder from above

      9. +

    9. Install the +Dev Containers +extension for Visual Studio Code, this extension allows you to use docker +containers as a development backend.

      10. +

    10. Once this is installed, you’ll be prompted to reload Visual Studio Code, do +so

      11. +

    11. At the bottom right of your Visual Studio Code window you should have a new +box prompting you to re-open the window as a container. Hit yes.

      12. +

    12. Windows Only Update your Visual Studio Code settings as documented here: +https://code.visualstudio.com/docs/editor/integrated-terminal#_configuration +to use Bash on Ubuntu (on Windows) eg: +"terminal.integrated.shell.windows": "C:\\Windows\\System32\\bash.exe"

      13. +

    13. Now your local machine is building a docker image that has all the tools +necessary to build and test Matter. This can take some time, but will +eventually complete and open up the source tree

      14. +
    +
    +
    +

    Bootstrapping your source tree (one time)#

    +
      +

    1. Under the “Terminal” menu (or using another shortcut to the same tool), +select “Run Task…”

      2. +

    2. Select the “Bootstrap” task

      3. +
    +
    +
    +

    Building the Source Tree#

    +
      +

    1. Under the “Terminal” menu select “Run Build Task…”

      2. +
    +
    +
    +

    Tasks#

    +

    Located in the tasks json file you’ll find a list of +tasks that can be run from the “Run Task…” command. Example tasks are “Clean”, +“Run Pretty Check”

    +

    Developers are encouraged to add tasks to the +tasks json over time to make sure everyone is using the +same base configuration and build.

    +
    +

    Current base tasks are listed here#

    +
      +

    • Main Build - Build the default configuration (i.e., Linux OpenSSL)

      • +

    • Run Unit and Functional Tests - Test the default configuration

      • +

    • Build & Test (all) - Build & Test various configurations (Linux variants, +Android, EFR32)

      • +

    • Update compilation database - Update the database used by IntelliSense +(needed for cross references, completion)

      • +

    • Bootstrap - On a clean tree, pull in the third party dependencies required

      • +

    • Clean Output - Remove build artifacts

      • +

    • Clean Tree - Full (and destructive) git clean of the tree

      • +
    +
    +
    +
    +

    Launch Tasks#

    +

    Located in the launch json file you’ll find a list of +build & run jobs that can be run from the “Run” tab and start a run or debug +session.

    +

    Developers are encouraged to add tasks to the +launch json over time to make sure everyone is using +the same base debugging setup.

    +
    +
    +

    Submitting a Pull Request - Practical Advice#

    +
    +

    Before submitting a PR, make sure these commands run and succeed#

    +
      +

    • Run task: “Build & Test (all)”

      • +
    +
    +
    +
    +

    Common Issues#

    + +
    +
    +

    Docker FAQ#

    +
    +

    DNS problem: can’t resolve archive.ubuntu.com#

    +

    A common problem encountered is that a container can’t resolve +archive.ubuntu.com and can’t install anything via apt-get, during the +creation of the container image, resulting in an error like:

    +
    E: Package 'locales' has no installation candidate
+The command '/bin/sh -c apt-get install -y locales && localedef -i en_US -c -f UTF-8 -A /usr/share/locale/locale.alias en_US.UTF-8' returned a non-zero code: 100
+
    +
    +

    Most common reason for this is that the DNS for docker daemon has not been set +up correctly and is simply using a default: 8.8.8.8, which in many corporate or +more secure environments is not accessible. A typical solution for this is to +put a following key/value into your system-wide docker daemon.json (Typically +located under /etc/docker/daemon.json on a Linux system):

    +
    "dns": ["<<IP ADDRESS OF YOUR NAMESERVER>>", "8.8.8.8"]
+
    +
    +

    You can obtain the address you should put into that line of your nameserver by +running:

    +
    nmcli dev show | grep 'IP4.DNS'
+
    +
    +

    After you update the dns, you should restart docker, specific to your system. On +a typical Linux workstation, you do this via:

    +
    sudo service docker restart
+
    +
    +

    Alternatively, you can also pass the --dns argument to your docker daemon, but +creating a daemon.json and following the above method will solve the problem +system-wide.

    +
    +
    +
    +

    Visual Studio Code FAQ#

    + +
    + +
    + + +
    + + + + + + + + +
    + + + +
    + +
    +
    + Contents +
    +
    + +
    + + +
    + + + +
    +
    +
    + + + + + + + + \ No newline at end of file diff --git a/_images/BL602-IoT-Matter_V1.png b/_images/BL602-IoT-Matter_V1.png new file mode 100644 index 000000000000..6cb4dc049f6e Binary files /dev/null and b/_images/BL602-IoT-Matter_V1.png differ diff --git a/_images/CHIPTool_device_commissioned.png b/_images/CHIPTool_device_commissioned.png new file mode 100644 index 000000000000..8756b4dbf6b0 Binary files /dev/null and b/_images/CHIPTool_device_commissioned.png differ diff --git a/_images/Logo_RGB_H-small.png b/_images/Logo_RGB_H-small.png new file mode 100644 index 000000000000..d9f2c9570c14 Binary files /dev/null and b/_images/Logo_RGB_H-small.png differ diff --git a/_images/Matter_Arch_Overview.png b/_images/Matter_Arch_Overview.png new file mode 100644 index 000000000000..6521fa71ad45 Binary files /dev/null and b/_images/Matter_Arch_Overview.png differ diff --git a/_images/Matter_Layered_Arch.png b/_images/Matter_Layered_Arch.png new file mode 100644 index 000000000000..38ad03ef437f Binary files /dev/null and b/_images/Matter_Layered_Arch.png differ diff --git a/_images/RVC_app_state_diagram.png b/_images/RVC_app_state_diagram.png new file mode 100644 index 000000000000..dcef2ed731f1 Binary files /dev/null and b/_images/RVC_app_state_diagram.png differ diff --git a/_images/SDK_layers.png b/_images/SDK_layers.png new file mode 100644 index 000000000000..84ecda721535 Binary files /dev/null and b/_images/SDK_layers.png differ diff --git a/_images/bl706_dev_board.jpg b/_images/bl706_dev_board.jpg new file mode 100644 index 000000000000..a93cad7177e2 Binary files /dev/null and b/_images/bl706_dev_board.jpg differ diff --git a/_images/cc13x4_memmap.png b/_images/cc13x4_memmap.png new file mode 100644 index 000000000000..4442c6352efb Binary files /dev/null and b/_images/cc13x4_memmap.png differ diff --git a/_images/chiptool_main_screen.png b/_images/chiptool_main_screen.png new file mode 100644 index 000000000000..5720467a5c0a Binary files /dev/null and b/_images/chiptool_main_screen.png differ diff --git a/_images/cluster_attribute_read.png b/_images/cluster_attribute_read.png new file mode 100644 index 000000000000..5f073aca8067 Binary files /dev/null and b/_images/cluster_attribute_read.png differ diff --git a/_images/cluster_commands.png b/_images/cluster_commands.png new file mode 100644 index 000000000000..7df7a8a75412 Binary files /dev/null and b/_images/cluster_commands.png differ diff --git a/_images/cluster_initialization.png b/_images/cluster_initialization.png new file mode 100644 index 000000000000..9cf980e3f727 Binary files /dev/null and b/_images/cluster_initialization.png differ diff --git a/_images/debug_k32w1.jpg b/_images/debug_k32w1.jpg new file mode 100644 index 000000000000..407c781220c4 Binary files /dev/null and b/_images/debug_k32w1.jpg differ diff --git a/_images/endpoint1_edit_pencil.png b/_images/endpoint1_edit_pencil.png new file mode 100644 index 000000000000..d10e63688229 Binary files /dev/null and b/_images/endpoint1_edit_pencil.png differ diff --git a/_images/endpoint_edit_type.png b/_images/endpoint_edit_type.png new file mode 100644 index 000000000000..10e0b78c6893 Binary files /dev/null and b/_images/endpoint_edit_type.png differ diff --git a/_images/factory_data_overview.png b/_images/factory_data_overview.png new file mode 100644 index 000000000000..f2718ce708f8 Binary files /dev/null and b/_images/factory_data_overview.png differ diff --git a/_images/flash_location.JPG b/_images/flash_location.JPG new file mode 100644 index 000000000000..9ee50ba61173 Binary files /dev/null and b/_images/flash_location.JPG differ diff --git a/_images/form_web.JPG b/_images/form_web.JPG new file mode 100644 index 000000000000..a7b12111564d Binary files /dev/null and b/_images/form_web.JPG differ diff --git a/_images/import_demo.jpg b/_images/import_demo.jpg new file mode 100644 index 000000000000..6016c448a48e Binary files /dev/null and b/_images/import_demo.jpg differ diff --git a/_images/installed_sdks.jpg b/_images/installed_sdks.jpg new file mode 100644 index 000000000000..be3ad84380a8 Binary files /dev/null and b/_images/installed_sdks.jpg differ diff --git a/_images/integration_tests.png b/_images/integration_tests.png new file mode 100644 index 000000000000..dd83695cf201 Binary files /dev/null and b/_images/integration_tests.png differ diff --git a/_images/k32w-dk6-connectors.jpg b/_images/k32w-dk6-connectors.jpg new file mode 100644 index 000000000000..c4018fbd9bca Binary files /dev/null and b/_images/k32w-dk6-connectors.jpg differ diff --git a/_images/k32w-dk6.jpg b/_images/k32w-dk6.jpg new file mode 100644 index 000000000000..7c547b69a575 Binary files /dev/null and b/_images/k32w-dk6.jpg differ diff --git a/_images/k32w-se.jpg b/_images/k32w-se.jpg new file mode 100644 index 000000000000..691bffd8d395 Binary files /dev/null and b/_images/k32w-se.jpg differ diff --git a/_images/k32w1-evk.jpg b/_images/k32w1-evk.jpg new file mode 100644 index 000000000000..550f27433678 Binary files /dev/null and b/_images/k32w1-evk.jpg differ diff --git a/_images/matter_mbedos_overview_simplified.png b/_images/matter_mbedos_overview_simplified.png new file mode 100644 index 000000000000..065a5b7a44e1 Binary files /dev/null and b/_images/matter_mbedos_overview_simplified.png differ diff --git a/_images/matter_nrfconnect_overview_simplified_ncs.svg b/_images/matter_nrfconnect_overview_simplified_ncs.svg new file mode 100644 index 000000000000..21316c04f125 --- /dev/null +++ b/_images/matter_nrfconnect_overview_simplified_ncs.svg @@ -0,0 +1,314 @@ + + + + + + + + Page-1 + + Sheet.3186 + User application + + User application + + Sheet.3188 + Thread stack (OpenThread) + + Thread stack (OpenThread) + + Sheet.3189 + + + + Sheet.3192 + Zephyr integration + + Zephyr integration + + Sheet.3194 + nRF IEEE 802.15.4 radio driver + + nRF IEEE 802.15.4 radio driver + + Sheet.3195 + + + + Sheet.3196 + + + + Sheet.3197 + Zephyr network layer + + Zephyr network layer + + Sheet.3198 + UDP + + UDP + + Sheet.3200 + TCP + + TCP + + Sheet.3202 + IPv6 + + IPv6 + + Sheet.3203 + + + + Sheet.3204 + Drivers and modules + + Drivers and modules + + Sheet.3205 + Crypto backends + + Crypto backends + + Sheet.3206 + NFC + + NFC + + Sheet.3207 + DFU + + DFU + + Sheet.3208 + Partition Manager + + Partition Manager + + Sheet.3209 + Zephyr APIs + + Zephyr APIs + + Sheet.3210 + Driver API + + Driver API + + Sheet.3211 + Crypto API + + Crypto API + + Sheet.3212 + Zephyr RTOS kernel + + Zephyr RTOS kernel + + Sheet.3213 + MCU bootloader + + MCU bootloader + + Sheet.3214 + mbedTLS + + mbedTLS + + Sheet.3226 + + + + Sheet.3228 + SoftDevice Controller + + SoftDevice Controller + + Sheet.3235 + Bluetooth® LE stack + + Bluetooth® LE stack + + Sheet.3241 + Matter stack + + Matter stack + + Sheet.3242 + Zephyr integration layer + + Zephyr integration layer + + Sheet.3227 + Zephyr host + + Zephyr host + + Sheet.3229 + L2CAP + + L2CAP + + Sheet.3230 + GATT + + GATT + + Sheet.3231 + ATT + + ATT + + Sheet.3232 + GAP + + GAP + + Sheet.3233 + + + + Sheet.3234 + SMP + + SMP + + Nordic Light Grey + + + + Sheet.3290 + + Sheet.3271 + + + + Sheet.3282 + Matter (built with GN) + + Matter (built with GN) + + + Sheet.3293 + + Sheet.3220 + + + + Sheet.3278 + Nordic component + + Nordic component + + + Sheet.3294 + + Sheet.3222 + + + + Sheet.3276 + Zephyr + + Zephyr + + + Sheet.3295 + + Sheet.3223 + + + + Sheet.3274 + nRF Connect SDK + + nRF Connect SDK + + + Sheet.3298 + + + + Sheet.3319 + + + + Sheet.3308 + Wi-Fi driver + + Wi-Fi driver + + Sheet.3318 + + + + Sheet.3309 + wpa_supplicant + + wpa_supplicant + + Sheet.3311 + + Sheet.3312 + + + + Sheet.3313 + Third-party + + Third-party + + + Sheet.3314 + Wi-Fi host + + Wi-Fi host + + Sheet.3317 + + + + Sheet.3190 + Multiprotocol Service Layer (MPSL) + + Multiprotocol Service Layer (MPSL) + + Sheet.3321 + + + + Sheet.3320 + + + + diff --git a/_images/matter_ti_overview_simplified.png b/_images/matter_ti_overview_simplified.png new file mode 100644 index 000000000000..2586fa41fdd9 Binary files /dev/null and b/_images/matter_ti_overview_simplified.png differ diff --git a/_images/mcu-set.PNG b/_images/mcu-set.PNG new file mode 100644 index 000000000000..1904593a66a8 Binary files /dev/null and b/_images/mcu-set.PNG differ diff --git a/_images/mcuboot_demo.PNG b/_images/mcuboot_demo.PNG new file mode 100644 index 000000000000..6584f2d53b53 Binary files /dev/null and b/_images/mcuboot_demo.PNG differ diff --git a/_images/mcuboot_monolithic_app.PNG b/_images/mcuboot_monolithic_app.PNG new file mode 100644 index 000000000000..8c9953c4a2c7 Binary files /dev/null and b/_images/mcuboot_monolithic_app.PNG differ diff --git a/_images/mcux-sdk-download.PNG b/_images/mcux-sdk-download.PNG new file mode 100644 index 000000000000..f1e236a896e0 Binary files /dev/null and b/_images/mcux-sdk-download.PNG differ diff --git a/_images/mcux-sdk-download.jpg b/_images/mcux-sdk-download.jpg new file mode 100644 index 000000000000..9dd4190b6d99 Binary files /dev/null and b/_images/mcux-sdk-download.jpg differ diff --git a/_images/mw320.jpg b/_images/mw320.jpg new file mode 100644 index 000000000000..bb76a6f6cb82 Binary files /dev/null and b/_images/mw320.jpg differ diff --git a/_images/mw320_console.jpg b/_images/mw320_console.jpg new file mode 100644 index 000000000000..c0067814c9f2 Binary files /dev/null and b/_images/mw320_console.jpg differ diff --git a/_images/nRF52840-DK-small.png b/_images/nRF52840-DK-small.png new file mode 100644 index 000000000000..729687fb21be Binary files /dev/null and b/_images/nRF52840-DK-small.png differ diff --git a/_images/nRF52840_DK_info-medium.jpg b/_images/nRF52840_DK_info-medium.jpg new file mode 100644 index 000000000000..03f60e925325 Binary files /dev/null and b/_images/nRF52840_DK_info-medium.jpg differ diff --git a/_images/nRF52840_Dongle-medium.jpg b/_images/nRF52840_Dongle-medium.jpg new file mode 100644 index 000000000000..3e7ec9adfc17 Binary files /dev/null and b/_images/nRF52840_Dongle-medium.jpg differ diff --git a/_images/nRF5340_DK_info-medium.jpg b/_images/nRF5340_DK_info-medium.jpg new file mode 100644 index 000000000000..d7b8f0bdfde2 Binary files /dev/null and b/_images/nRF5340_DK_info-medium.jpg differ diff --git a/_images/nRF7002-DK_Front-small.png b/_images/nRF7002-DK_Front-small.png new file mode 100644 index 000000000000..fbf84407fc3e Binary files /dev/null and b/_images/nRF7002-DK_Front-small.png differ diff --git a/_images/new_project.jpg b/_images/new_project.jpg new file mode 100644 index 000000000000..ce34586229bd Binary files /dev/null and b/_images/new_project.jpg differ diff --git a/_images/nrfconnect_android_connectivity.png b/_images/nrfconnect_android_connectivity.png new file mode 100644 index 000000000000..76138cb316ad Binary files /dev/null and b/_images/nrfconnect_android_connectivity.png differ diff --git a/_images/nxp_hw_connectivity.JPG b/_images/nxp_hw_connectivity.JPG new file mode 100644 index 000000000000..80e19b30dfc6 Binary files /dev/null and b/_images/nxp_hw_connectivity.JPG differ diff --git a/_images/on_off_cluster.png b/_images/on_off_cluster.png new file mode 100644 index 000000000000..4a2b9af6869a Binary files /dev/null and b/_images/on_off_cluster.png differ diff --git a/_images/ota_topology.JPG b/_images/ota_topology.JPG new file mode 100644 index 000000000000..75fc40a70e3b Binary files /dev/null and b/_images/ota_topology.JPG differ diff --git a/_images/ota_topology1.JPG b/_images/ota_topology1.JPG new file mode 100644 index 000000000000..75fc40a70e3b Binary files /dev/null and b/_images/ota_topology1.JPG differ diff --git a/_images/power_conf.JPG b/_images/power_conf.JPG new file mode 100644 index 000000000000..2c03e812c8f6 Binary files /dev/null and b/_images/power_conf.JPG differ diff --git a/_images/power_view.JPG b/_images/power_view.JPG new file mode 100644 index 000000000000..c7a33b80c873 Binary files /dev/null and b/_images/power_view.JPG differ diff --git a/_images/select_enabled_clusters.png b/_images/select_enabled_clusters.png new file mode 100644 index 000000000000..92f41577dad2 Binary files /dev/null and b/_images/select_enabled_clusters.png differ diff --git a/_images/silabs_logo.png b/_images/silabs_logo.png new file mode 100644 index 000000000000..85cfcceb7434 Binary files /dev/null and b/_images/silabs_logo.png differ diff --git a/_images/ssbl_bin.JPG b/_images/ssbl_bin.JPG new file mode 100644 index 000000000000..fb871d45aeb5 Binary files /dev/null and b/_images/ssbl_bin.JPG differ diff --git a/_images/ssbl_multi_image.JPG b/_images/ssbl_multi_image.JPG new file mode 100644 index 000000000000..31449b25cf26 Binary files /dev/null and b/_images/ssbl_multi_image.JPG differ diff --git a/_images/ssbl_select.JPG b/_images/ssbl_select.JPG new file mode 100644 index 000000000000..79ea51b62698 Binary files /dev/null and b/_images/ssbl_select.JPG differ diff --git a/_images/ssbl_simple_hash.JPG b/_images/ssbl_simple_hash.JPG new file mode 100644 index 000000000000..9ec701b0bb1d Binary files /dev/null and b/_images/ssbl_simple_hash.JPG differ diff --git a/_images/thread_credentials.png b/_images/thread_credentials.png new file mode 100644 index 000000000000..29d89c684831 Binary files /dev/null and b/_images/thread_credentials.png differ diff --git a/_images/toolchain.JPG b/_images/toolchain.JPG new file mode 100644 index 000000000000..068ebfb35e1e Binary files /dev/null and b/_images/toolchain.JPG differ diff --git a/_images/unit_testable_clusters.png b/_images/unit_testable_clusters.png new file mode 100644 index 000000000000..61f6c51f59b7 Binary files /dev/null and b/_images/unit_testable_clusters.png differ diff --git a/_images/unit_testable_clusters_all_classes.png b/_images/unit_testable_clusters_all_classes.png new file mode 100644 index 000000000000..6cd8f903b60a Binary files /dev/null and b/_images/unit_testable_clusters_all_classes.png differ diff --git a/_images/unit_testable_clusters_context.png b/_images/unit_testable_clusters_context.png new file mode 100644 index 000000000000..3a42eca37be2 Binary files /dev/null and b/_images/unit_testable_clusters_context.png differ diff --git a/_images/unit_testable_clusters_driver.png b/_images/unit_testable_clusters_driver.png new file mode 100644 index 000000000000..bf97434fb579 Binary files /dev/null and b/_images/unit_testable_clusters_driver.png differ diff --git a/_images/unit_testable_clusters_logic.png b/_images/unit_testable_clusters_logic.png new file mode 100644 index 000000000000..9ebed283777b Binary files /dev/null and b/_images/unit_testable_clusters_logic.png differ diff --git a/_images/unit_testable_clusters_server.png b/_images/unit_testable_clusters_server.png new file mode 100644 index 000000000000..d8632e73a323 Binary files /dev/null and b/_images/unit_testable_clusters_server.png differ diff --git a/_images/unit_tests.png b/_images/unit_tests.png new file mode 100644 index 000000000000..95b29b415c96 Binary files /dev/null and b/_images/unit_tests.png differ diff --git a/_images/workflow_of_casting_video_player.png b/_images/workflow_of_casting_video_player.png new file mode 100644 index 000000000000..7b8abeb30e40 Binary files /dev/null and b/_images/workflow_of_casting_video_player.png differ diff --git a/_images/zap1.png b/_images/zap1.png new file mode 100644 index 000000000000..4356cda98e85 Binary files /dev/null and b/_images/zap1.png differ diff --git a/_images/zap2.png b/_images/zap2.png new file mode 100644 index 000000000000..cd73e0417c25 Binary files /dev/null and b/_images/zap2.png differ diff --git a/_images/zap3.png b/_images/zap3.png new file mode 100644 index 000000000000..018778c7dcee Binary files /dev/null and b/_images/zap3.png differ diff --git a/_images/zap4.png b/_images/zap4.png new file mode 100644 index 000000000000..92ab5cce5186 Binary files /dev/null and b/_images/zap4.png differ diff --git a/_images/zap5.png b/_images/zap5.png new file mode 100644 index 000000000000..5ca690814470 Binary files /dev/null and b/_images/zap5.png differ diff --git a/_images/zap6.png b/_images/zap6.png new file mode 100644 index 000000000000..0901e225fbff Binary files /dev/null and b/_images/zap6.png differ diff --git a/_images/zap_compiler.png b/_images/zap_compiler.png new file mode 100644 index 000000000000..68c1e09395a0 Binary files /dev/null and b/_images/zap_compiler.png differ diff --git a/_sources/BUG_REPORT.md b/_sources/BUG_REPORT.md new file mode 100644 index 000000000000..1d290a400289 --- /dev/null +++ b/_sources/BUG_REPORT.md @@ -0,0 +1,109 @@ +# Reporting bugs + +## Writing an effective bug report + +When reporting a bug, start with the question +`What does a bug report need to tell the developer`. + +Generally you want the following parts covered: + +- What is the problem + +- How can the developer reproduce the problem (to see it for themselves), to + bisect when it was introduced or to find if it got fixed already. + +- At what point does the problem occur + +- What environment did this occur in + +Make sure the above items are covered and the bug is easy to review and parse: + +- **Title** should clearly describe the problem. Bugs are often sorted from + the issue list which only contains the title + +- **Logs** should generally be attachments (drag & drop or click on bottom bar + when entering issue text) and not inline with the issue. + +- **Reproduction steps** and **environment** should be clearly highlighted. If + running commands reproduce the issue (very common), the commands should be + in a code block/script format. + +### Describing the problem + +Make sure the issue is obvious or provide a link explaining why the expected +result is not met. + +Examples: + +- `(Core dump) seen` is obvious since there should be no core dumps + +- `Failure trying to read attribute X in cluster Y which is marked MANDATORY in the spec` + references the spec and describes why attribute read should succeed. + +- `Failure trying to write attribute X in cluster Y, which is enabled since cluster FeatureMap enabled X and spec describes as writable.` + references the spec and explicitly states that an optional attribute is + enabled based on device status + +- `Running certification test TC-A-B-C (link included) fails at step 3: test case asks for command to succeed, I get ACCESS_DENIED instead` + describes a pre-defined test case that is expected to pass but fails. Note + that full link to the test description is needed (and should be covered by + 'how to reproduce' part) + +Unless manually curated (e.g. few lines showing the problem), logs should be +always attachments and not inlined in the bug as the make the bug report too +long. + +### Reproduction steps and when does the issue occur + +Include all steps needed to reproduce the problem. Link any supporting +documentation. + +If stating something of the form `TC-A-B-C step 4 fails` then there should be a +link to TC-A-B-C and ideally a list of the commands of each step since test +cases may change over time. + +The bug report should contain all the information for a developer to reproduce +the issue without needing to have access to CHIP Test case repository (not +everyone does) + +### Environment for reproduction + +Assume that the developer will want to reproduce the issue and will try to +mirror your environment to a reasonable degree. For this, at a minimum the +platforms on which everything is running is needed. + +Try to provide as much information as seems relevant. At a minimum this could +look like +`Failed to commission nrf board using chip-tool running on linux. Used build on SHA abcde...`. +This provides basic information (use nrf board, use chip-tool on linux, default +build) to get started. Beyond that, you can refine if more items seem relevant: + +- `Tested on TE9` or `Tested on interop branch xyz` gives a build reference + point. Useful when branches/tags are used instead of master branch as + development happens on master branch. + +- `Thread devices fail, tested with qpg and efr32` shows that this seems to be + a general thread issue and developer can investigate on multiple of them + +* `Tested with avahi-build and it passes/fails` helps the developer with + information of non-default builds that pass/fail to narrow down the problem + +* `Passes with darwin-framework-tool and repl but fails with chip-tool` helps + the developer in narrowing down the problem + +### Additional information + +Providing additional information that can be helpful is encouraged. Each bug +report is different here. Some examples: + +- `This worked last week (around Jan 5) but started failing in recent master builds` + +- `Specification changed this attribute from optional to mandatory so this may be the cause of the issue` + +- `This issue may be related to #1234 as the same error is seen, however the reproduction steps seemed distinct enough that I opened a new issue` + +- `While running this, I observed 100% CPU before the operation finally timed out` + +- `While running this test, I observed device under test rebooting, logs attached.` + +- `This only happens intermittently - I see it about 30% of the time` diff --git a/_sources/ERROR_CODES.md b/_sources/ERROR_CODES.md new file mode 100644 index 000000000000..82a6219416db --- /dev/null +++ b/_sources/ERROR_CODES.md @@ -0,0 +1,264 @@ +# Matter SDK `CHIP_ERROR` enums values + +This file was **AUTOMATICALLY** generated by +`python scripts/error_table.py > docs/ERROR_CODES.md`. DO NOT EDIT BY HAND! + +## Table of contents +- [SDK Core errors: range `0x000..0x0FF`](#sdk-core-errors) +- [SDK Inet Layer errors: range `0x100..0x1FF`](#sdk-inet-layer-errors) +- [SDK Device Layer errors: range `0x200..0x2FF`](#sdk-device-layer-errors) +- [ASN1 Layer errors: range `0x300..0x3FF`](#asn1-layer-errors) +- [BLE Layer errors: range `0x400..0x4FF`](#ble-layer-errors) +- [IM Global errors errors: range `0x500..0x5FF`](#im-global-errors-errors) + +## SDK Core errors + +| Decimal | Hex | Name | +|-----------|-------|----------------------------------------------------| +| 0 | 0x00 | `CHIP_NO_ERROR` | +| 1 | 0x01 | `CHIP_ERROR_SENDING_BLOCKED` | +| 2 | 0x02 | `CHIP_ERROR_CONNECTION_ABORTED` | +| 3 | 0x03 | `CHIP_ERROR_INCORRECT_STATE` | +| 4 | 0x04 | `CHIP_ERROR_MESSAGE_TOO_LONG` | +| 5 | 0x05 | `CHIP_ERROR_RECURSION_DEPTH_LIMIT` | +| 6 | 0x06 | `CHIP_ERROR_TOO_MANY_UNSOLICITED_MESSAGE_HANDLERS` | +| 7 | 0x07 | `CHIP_ERROR_NO_UNSOLICITED_MESSAGE_HANDLER` | +| 8 | 0x08 | `CHIP_ERROR_NO_CONNECTION_HANDLER` | +| 9 | 0x09 | `CHIP_ERROR_TOO_MANY_PEER_NODES` | +| 10 | 0x0A | `CHIP_ERROR_SENTINEL` | +| 11 | 0x0B | `CHIP_ERROR_NO_MEMORY` | +| 12 | 0x0C | `CHIP_ERROR_NO_MESSAGE_HANDLER` | +| 13 | 0x0D | `CHIP_ERROR_MESSAGE_INCOMPLETE` | +| 14 | 0x0E | `CHIP_ERROR_DATA_NOT_ALIGNED` | +| 15 | 0x0F | `CHIP_ERROR_UNKNOWN_KEY_TYPE` | +| 16 | 0x10 | `CHIP_ERROR_KEY_NOT_FOUND` | +| 17 | 0x11 | `CHIP_ERROR_WRONG_ENCRYPTION_TYPE` | +| 18 | 0x12 | `CHIP_ERROR_INVALID_UTF8` | +| 19 | 0x13 | `CHIP_ERROR_INTEGRITY_CHECK_FAILED` | +| 20 | 0x14 | `CHIP_ERROR_INVALID_SIGNATURE` | +| 21 | 0x15 | `CHIP_ERROR_INVALID_TLV_CHAR_STRING` | +| 22 | 0x16 | `CHIP_ERROR_LIT_SUBSCRIBE_INACTIVE_TIMEOUT` | +| 23 | 0x17 | `CHIP_ERROR_UNSUPPORTED_SIGNATURE_TYPE` | +| 24 | 0x18 | `CHIP_ERROR_INVALID_MESSAGE_LENGTH` | +| 25 | 0x19 | `CHIP_ERROR_BUFFER_TOO_SMALL` | +| 26 | 0x1A | `CHIP_ERROR_DUPLICATE_KEY_ID` | +| 27 | 0x1B | `CHIP_ERROR_WRONG_KEY_TYPE` | +| 28 | 0x1C | `CHIP_ERROR_UNINITIALIZED` | +| 29 | 0x1D | `CHIP_ERROR_INVALID_IPK` | +| 30 | 0x1E | `CHIP_ERROR_INVALID_STRING_LENGTH` | +| 31 | 0x1F | `CHIP_ERROR_INVALID_LIST_LENGTH` | +| 33 | 0x21 | `CHIP_ERROR_END_OF_TLV` | +| 34 | 0x22 | `CHIP_ERROR_TLV_UNDERRUN` | +| 35 | 0x23 | `CHIP_ERROR_INVALID_TLV_ELEMENT` | +| 36 | 0x24 | `CHIP_ERROR_INVALID_TLV_TAG` | +| 37 | 0x25 | `CHIP_ERROR_UNKNOWN_IMPLICIT_TLV_TAG` | +| 38 | 0x26 | `CHIP_ERROR_WRONG_TLV_TYPE` | +| 39 | 0x27 | `CHIP_ERROR_TLV_CONTAINER_OPEN` | +| 42 | 0x2A | `CHIP_ERROR_INVALID_MESSAGE_TYPE` | +| 43 | 0x2B | `CHIP_ERROR_UNEXPECTED_TLV_ELEMENT` | +| 45 | 0x2D | `CHIP_ERROR_NOT_IMPLEMENTED` | +| 46 | 0x2E | `CHIP_ERROR_INVALID_ADDRESS` | +| 47 | 0x2F | `CHIP_ERROR_INVALID_ARGUMENT` | +| 48 | 0x30 | `CHIP_ERROR_INVALID_PATH_LIST` | +| 49 | 0x31 | `CHIP_ERROR_INVALID_DATA_LIST` | +| 50 | 0x32 | `CHIP_ERROR_TIMEOUT` | +| 51 | 0x33 | `CHIP_ERROR_INVALID_DEVICE_DESCRIPTOR` | +| 56 | 0x38 | `CHIP_ERROR_INVALID_PASE_PARAMETER` | +| 59 | 0x3B | `CHIP_ERROR_INVALID_USE_OF_SESSION_KEY` | +| 60 | 0x3C | `CHIP_ERROR_CONNECTION_CLOSED_UNEXPECTEDLY` | +| 61 | 0x3D | `CHIP_ERROR_MISSING_TLV_ELEMENT` | +| 62 | 0x3E | `CHIP_ERROR_RANDOM_DATA_UNAVAILABLE` | +| 65 | 0x41 | `CHIP_ERROR_HOST_PORT_LIST_EMPTY` | +| 69 | 0x45 | `CHIP_ERROR_FORCED_RESET` | +| 70 | 0x46 | `CHIP_ERROR_NO_ENDPOINT` | +| 71 | 0x47 | `CHIP_ERROR_INVALID_DESTINATION_NODE_ID` | +| 72 | 0x48 | `CHIP_ERROR_NOT_CONNECTED` | +| 74 | 0x4A | `CHIP_ERROR_CA_CERT_NOT_FOUND` | +| 75 | 0x4B | `CHIP_ERROR_CERT_PATH_LEN_CONSTRAINT_EXCEEDED` | +| 76 | 0x4C | `CHIP_ERROR_CERT_PATH_TOO_LONG` | +| 77 | 0x4D | `CHIP_ERROR_CERT_USAGE_NOT_ALLOWED` | +| 78 | 0x4E | `CHIP_ERROR_CERT_EXPIRED` | +| 79 | 0x4F | `CHIP_ERROR_CERT_NOT_VALID_YET` | +| 80 | 0x50 | `CHIP_ERROR_UNSUPPORTED_CERT_FORMAT` | +| 81 | 0x51 | `CHIP_ERROR_UNSUPPORTED_ELLIPTIC_CURVE` | +| 83 | 0x53 | `CHIP_ERROR_CERT_NOT_FOUND` | +| 84 | 0x54 | `CHIP_ERROR_INVALID_CASE_PARAMETER` | +| 86 | 0x56 | `CHIP_ERROR_CERT_LOAD_FAILED` | +| 87 | 0x57 | `CHIP_ERROR_CERT_NOT_TRUSTED` | +| 89 | 0x59 | `CHIP_ERROR_WRONG_CERT_DN` | +| 92 | 0x5C | `CHIP_ERROR_WRONG_NODE_ID` | +| 100 | 0x64 | `CHIP_ERROR_RETRANS_TABLE_FULL` | +| 104 | 0x68 | `CHIP_ERROR_TRANSACTION_CANCELED` | +| 107 | 0x6B | `CHIP_ERROR_INVALID_SUBSCRIPTION` | +| 108 | 0x6C | `CHIP_ERROR_UNSUPPORTED_CHIP_FEATURE` | +| 112 | 0x70 | `CHIP_ERROR_UNSOLICITED_MSG_NO_ORIGINATOR` | +| 113 | 0x71 | `CHIP_ERROR_INVALID_FABRIC_INDEX` | +| 114 | 0x72 | `CHIP_ERROR_TOO_MANY_CONNECTIONS` | +| 115 | 0x73 | `CHIP_ERROR_SHUT_DOWN` | +| 116 | 0x74 | `CHIP_ERROR_CANCELLED` | +| 118 | 0x76 | `CHIP_ERROR_TLV_TAG_NOT_FOUND` | +| 119 | 0x77 | `CHIP_ERROR_MISSING_SECURE_SESSION` | +| 120 | 0x78 | `CHIP_ERROR_INVALID_ADMIN_SUBJECT` | +| 121 | 0x79 | `CHIP_ERROR_INSUFFICIENT_PRIVILEGE` | +| 125 | 0x7D | `CHIP_ERROR_MESSAGE_COUNTER_EXHAUSTED` | +| 126 | 0x7E | `CHIP_ERROR_FABRIC_EXISTS` | +| 127 | 0x7F | `CHIP_ERROR_ENDPOINT_EXISTS` | +| 128 | 0x80 | `CHIP_ERROR_WRONG_ENCRYPTION_TYPE_FROM_PEER` | +| 133 | 0x85 | `CHIP_ERROR_INVALID_KEY_ID` | +| 134 | 0x86 | `CHIP_ERROR_INVALID_TIME` | +| 142 | 0x8E | `CHIP_ERROR_SCHEMA_MISMATCH` | +| 143 | 0x8F | `CHIP_ERROR_INVALID_INTEGER_VALUE` | +| 146 | 0x92 | `CHIP_ERROR_BAD_REQUEST` | +| 157 | 0x9D | `CHIP_ERROR_WRONG_CERT_TYPE` | +| 159 | 0x9F | `CHIP_ERROR_PERSISTED_STORAGE_FAILED` | +| 160 | 0xA0 | `CHIP_ERROR_PERSISTED_STORAGE_VALUE_NOT_FOUND` | +| 161 | 0xA1 | `CHIP_ERROR_IM_FABRIC_DELETED` | +| 164 | 0xA4 | `CHIP_ERROR_IN_PROGRESS` | +| 165 | 0xA5 | `CHIP_ERROR_ACCESS_DENIED` | +| 166 | 0xA6 | `CHIP_ERROR_UNKNOWN_RESOURCE_ID` | +| 167 | 0xA7 | `CHIP_ERROR_VERSION_MISMATCH` | +| 171 | 0xAB | `CHIP_ERROR_EVENT_ID_FOUND` | +| 172 | 0xAC | `CHIP_ERROR_INTERNAL` | +| 173 | 0xAD | `CHIP_ERROR_OPEN_FAILED` | +| 174 | 0xAE | `CHIP_ERROR_READ_FAILED` | +| 175 | 0xAF | `CHIP_ERROR_WRITE_FAILED` | +| 176 | 0xB0 | `CHIP_ERROR_DECODE_FAILED` | +| 179 | 0xB3 | `CHIP_ERROR_DNS_SD_UNAUTHORIZED` | +| 180 | 0xB4 | `CHIP_ERROR_MDNS_COLLISION` | +| 181 | 0xB5 | `CHIP_ERROR_IM_MALFORMED_ATTRIBUTE_PATH_IB` | +| 182 | 0xB6 | `CHIP_ERROR_IM_MALFORMED_EVENT_PATH_IB` | +| 185 | 0xB9 | `CHIP_ERROR_IM_MALFORMED_COMMAND_DATA_IB` | +| 186 | 0xBA | `CHIP_ERROR_IM_MALFORMED_EVENT_DATA_IB` | +| 187 | 0xBB | `CHIP_ERROR_MAXIMUM_PATHS_PER_INVOKE_EXCEEDED` | +| 188 | 0xBC | `CHIP_ERROR_PEER_NODE_NOT_FOUND` | +| 189 | 0xBD | `CHIP_ERROR_HSM` | +| 191 | 0xBF | `CHIP_ERROR_REAL_TIME_NOT_SYNCED` | +| 192 | 0xC0 | `CHIP_ERROR_UNEXPECTED_EVENT` | +| 193 | 0xC1 | `CHIP_ERROR_ENDPOINT_POOL_FULL` | +| 194 | 0xC2 | `CHIP_ERROR_INBOUND_MESSAGE_TOO_BIG` | +| 195 | 0xC3 | `CHIP_ERROR_OUTBOUND_MESSAGE_TOO_BIG` | +| 196 | 0xC4 | `CHIP_ERROR_DUPLICATE_MESSAGE_RECEIVED` | +| 197 | 0xC5 | `CHIP_ERROR_INVALID_PUBLIC_KEY` | +| 198 | 0xC6 | `CHIP_ERROR_FABRIC_MISMATCH_ON_ICA` | +| 201 | 0xC9 | `CHIP_ERROR_NO_SHARED_TRUSTED_ROOT` | +| 202 | 0xCA | `CHIP_ERROR_IM_STATUS_CODE_RECEIVED` | +| 215 | 0xD7 | `CHIP_ERROR_IM_MALFORMED_DATA_VERSION_FILTER_IB` | +| 216 | 0xD8 | `CHIP_ERROR_NOT_FOUND` | +| 218 | 0xDA | `CHIP_ERROR_INVALID_FILE_IDENTIFIER` | +| 219 | 0xDB | `CHIP_ERROR_BUSY` | +| 220 | 0xDC | `CHIP_ERROR_MAX_RETRY_EXCEEDED` | +| 221 | 0xDD | `CHIP_ERROR_PROVIDER_LIST_EXHAUSTED` | +| 223 | 0xDF | `CHIP_ERROR_INVALID_SCHEME_PREFIX` | +| 224 | 0xE0 | `CHIP_ERROR_MISSING_URI_SEPARATOR` | +| 225 | 0xE1 | `CHIP_ERROR_HANDLER_NOT_SET` | + +## SDK Inet Layer errors + +| Decimal | Hex | Name | +|-----------|-------|-------------------------------------------| +| 257 | 0x101 | `INET_ERROR_WRONG_ADDRESS_TYPE` | +| 258 | 0x102 | `INET_ERROR_PEER_DISCONNECTED` | +| 265 | 0x109 | `INET_ERROR_HOST_NOT_FOUND` | +| 266 | 0x10A | `INET_ERROR_DNS_TRY_AGAIN` | +| 267 | 0x10B | `INET_ERROR_DNS_NO_RECOVERY` | +| 269 | 0x10D | `INET_ERROR_WRONG_PROTOCOL_TYPE` | +| 270 | 0x10E | `INET_ERROR_UNKNOWN_INTERFACE` | +| 272 | 0x110 | `INET_ERROR_ADDRESS_NOT_FOUND` | +| 273 | 0x111 | `INET_ERROR_HOST_NAME_TOO_LONG` | +| 274 | 0x112 | `INET_ERROR_INVALID_HOST_NAME` | +| 277 | 0x115 | `INET_ERROR_IDLE_TIMEOUT` | +| 279 | 0x117 | `INET_ERROR_INVALID_IPV6_PKT` | +| 280 | 0x118 | `INET_ERROR_INTERFACE_INIT_FAILURE` | +| 281 | 0x119 | `INET_ERROR_TCP_USER_TIMEOUT` | +| 282 | 0x11A | `INET_ERROR_TCP_CONNECT_TIMEOUT` | +| 283 | 0x11B | `INET_ERROR_INCOMPATIBLE_IP_ADDRESS_TYPE` | + +## SDK Device Layer errors + +| Decimal | Hex | Name | +|-----------|-------|---------------------------------------------| +| 513 | 0x201 | `CHIP_DEVICE_ERROR_CONFIG_NOT_FOUND` | +| 514 | 0x202 | `CHIP_DEVICE_ERROR_NOT_SERVICE_PROVISIONED` | +| 515 | 0x203 | `CHIP_DEVICE_ERROR_SOFTWARE_UPDATE_ABORTED` | +| 516 | 0x204 | `CHIP_DEVICE_ERROR_SOFTWARE_UPDATE_IGNORED` | + +## ASN1 Layer errors + +| Decimal | Hex | Name | +|-----------|-------|-----------------------------------| +| 768 | 0x300 | `ASN1_END` | +| 769 | 0x301 | `ASN1_ERROR_UNDERRUN` | +| 770 | 0x302 | `ASN1_ERROR_OVERFLOW` | +| 771 | 0x303 | `ASN1_ERROR_INVALID_STATE` | +| 772 | 0x304 | `ASN1_ERROR_MAX_DEPTH_EXCEEDED` | +| 773 | 0x305 | `ASN1_ERROR_INVALID_ENCODING` | +| 774 | 0x306 | `ASN1_ERROR_UNSUPPORTED_ENCODING` | +| 775 | 0x307 | `ASN1_ERROR_TAG_OVERFLOW` | +| 776 | 0x308 | `ASN1_ERROR_LENGTH_OVERFLOW` | +| 777 | 0x309 | `ASN1_ERROR_VALUE_OVERFLOW` | +| 778 | 0x30A | `ASN1_ERROR_UNKNOWN_OBJECT_ID` | + +## BLE Layer errors + +| Decimal | Hex | Name | +|-----------|-------|---------------------------------------------| +| 1025 | 0x401 | `BLE_ERROR_ADAPTER_UNAVAILABLE` | +| 1027 | 0x403 | `BLE_ERROR_NO_CONNECTION_RECEIVED_CALLBACK` | +| 1028 | 0x404 | `BLE_ERROR_CENTRAL_UNSUBSCRIBED` | +| 1029 | 0x405 | `BLE_ERROR_GATT_SUBSCRIBE_FAILED` | +| 1030 | 0x406 | `BLE_ERROR_GATT_UNSUBSCRIBE_FAILED` | +| 1031 | 0x407 | `BLE_ERROR_GATT_WRITE_FAILED` | +| 1032 | 0x408 | `BLE_ERROR_GATT_INDICATE_FAILED` | +| 1035 | 0x40B | `BLE_ERROR_CHIPOBLE_PROTOCOL_ABORT` | +| 1036 | 0x40C | `BLE_ERROR_REMOTE_DEVICE_DISCONNECTED` | +| 1037 | 0x40D | `BLE_ERROR_APP_CLOSED_CONNECTION` | +| 1039 | 0x40F | `BLE_ERROR_NOT_CHIP_DEVICE` | +| 1040 | 0x410 | `BLE_ERROR_INCOMPATIBLE_PROTOCOL_VERSIONS` | +| 1043 | 0x413 | `BLE_ERROR_INVALID_FRAGMENT_SIZE` | +| 1044 | 0x414 | `BLE_ERROR_START_TIMER_FAILED` | +| 1045 | 0x415 | `BLE_ERROR_CONNECT_TIMED_OUT` | +| 1046 | 0x416 | `BLE_ERROR_RECEIVE_TIMED_OUT` | +| 1047 | 0x417 | `BLE_ERROR_INVALID_MESSAGE` | +| 1048 | 0x418 | `BLE_ERROR_FRAGMENT_ACK_TIMED_OUT` | +| 1049 | 0x419 | `BLE_ERROR_KEEP_ALIVE_TIMED_OUT` | +| 1050 | 0x41A | `BLE_ERROR_NO_CONNECT_COMPLETE_CALLBACK` | +| 1051 | 0x41B | `BLE_ERROR_INVALID_ACK` | +| 1052 | 0x41C | `BLE_ERROR_REASSEMBLER_MISSING_DATA` | +| 1053 | 0x41D | `BLE_ERROR_INVALID_BTP_HEADER_FLAGS` | +| 1054 | 0x41E | `BLE_ERROR_INVALID_BTP_SEQUENCE_NUMBER` | +| 1055 | 0x41F | `BLE_ERROR_REASSEMBLER_INCORRECT_STATE` | + +## IM Global errors errors + +| Decimal | Hex | Name | +|-----------|-------|----------------------------| +| 1280 | 0x500 | `SUCCESS` | +| 1281 | 0x501 | `FAILURE` | +| 1405 | 0x57D | `INVALID_SUBSCRIPTION` | +| 1406 | 0x57E | `UNSUPPORTED_ACCESS` | +| 1407 | 0x57F | `UNSUPPORTED_ENDPOINT` | +| 1408 | 0x580 | `INVALID_ACTION` | +| 1409 | 0x581 | `UNSUPPORTED_COMMAND` | +| 1413 | 0x585 | `INVALID_COMMAND` | +| 1414 | 0x586 | `UNSUPPORTED_ATTRIBUTE` | +| 1415 | 0x587 | `CONSTRAINT_ERROR` | +| 1416 | 0x588 | `UNSUPPORTED_WRITE` | +| 1417 | 0x589 | `RESOURCE_EXHAUSTED` | +| 1419 | 0x58B | `NOT_FOUND` | +| 1420 | 0x58C | `UNREPORTABLE_ATTRIBUTE` | +| 1421 | 0x58D | `INVALID_DATA_TYPE` | +| 1423 | 0x58F | `UNSUPPORTED_READ` | +| 1426 | 0x592 | `DATA_VERSION_MISMATCH` | +| 1428 | 0x594 | `TIMEOUT` | +| 1436 | 0x59C | `BUSY` | +| 1475 | 0x5C3 | `UNSUPPORTED_CLUSTER` | +| 1477 | 0x5C5 | `NO_UPSTREAM_SUBSCRIPTION` | +| 1478 | 0x5C6 | `NEEDS_TIMED_INTERACTION` | +| 1479 | 0x5C7 | `UNSUPPORTED_EVENT` | +| 1480 | 0x5C8 | `PATHS_EXHAUSTED` | +| 1481 | 0x5C9 | `TIMED_REQUEST_MISMATCH` | +| 1482 | 0x5CA | `FAILSAFE_REQUIRED` | +| 1483 | 0x5CB | `INVALID_IN_STATE` | +| 1484 | 0x5CC | `NO_COMMAND_RESPONSE` | +| 1520 | 0x5F0 | `WRITE_IGNORED` | + diff --git a/_sources/PROJECT_FLOW.md b/_sources/PROJECT_FLOW.md new file mode 100644 index 000000000000..d8579a4e9621 --- /dev/null +++ b/_sources/PROJECT_FLOW.md @@ -0,0 +1,85 @@ +## Matter Project Flow + +This section is intended to cover how Matter uses GitHub Projects, Issues, +Milestones, Releases, and Branches for program/project management in the code +repository. + +### Issues + +Matter uses issues as simple problem descriptions or feature requests. In +general, all work contributed to the repository in the form of pull requests +(PR) should be under the auspices of some open issue. This may seem onerous and +in some cases duplicative, so consider these guidelines when deciding whether +you can get away with not creating an issue: + +- Trivial fixes: issues can function as TODO lists, simple reminders that + something should be addressed. Sometimes, though, the work required to fix + is smaller than the work required to write the issue. +- Issues intended to be addressed by a PR may not actually be fixed or may + regress. +- Issues can span PRs (as PRs should be as small as possible, but no smaller). +- Issues help form an important basis for release notes. Any PR that addresses + a problem that should have release visibility, please do open an issue. + +### Pull requests + +Pull requests should be small and address a single, specific change to the code +base. They should be easy to review, as a "yes, that's better". Refrain from +requesting review until all PR checks have completed successfully, lest you tire +your reviewers. + +PR Don'ts: + +- Don't combine unrelated changes. E.g. if the PR addresses a bug in some C + code, an update to the top-level .gitignore doesn't belong. +- Don't make stacks. E.g. if a change in a component requires a new feature or + even a small tweak in one or more of its dependencies, each dependency + change belongs in its own separate PR. + +### Milestones + +In Matter parlance, a milestone is simply a tag for an expected due date or +release. Milestones are intended to help contributors and their managers to +prioritize work. There are 2 types: Date-based and Release-based. + +#### Date-based + +Date-based milestones are named for their due date, typically a Friday of some +week. Date-based milestones are normally assigned based on a guess about when +something's likely to bubble up and get done based on current work load and +resourcing. They are wishes, guesses. + +#### Release-based + +Release-based milestones are named for the release version and may have flexible +or subject-to-change due dates. Release-based milestones are intended to track +release blockers. + +A special "Not sure when" milestone is a marker for issues whose priority, +scope, or blocking status have not been determined. Monthly review of these is a +project goal. + +Issues without milestones are those that have yet to be considered for one of +the above. Weekly review of new issues is a project goal. + +### Projects + +Projects are collections of issues, pull requests, and notes intended to capture +larger efforts that don't fit in issues, have multiple-subsystems involved, or +may span multiple milestones. We use projects 2 ways: + +1. To track burn down on a larger task. When constructing such a project, it's + important to think in terms of something that will eventually have an end, + i.e. a definite scope. +2. To categorize issues, denote broader efforts without a definite time scope. + These projects might reflect or show burndown or percent complete, but are + mostly used to view where effort is going. + +Issues can belong to any number of projects, but should generally only belong to +one of the task-tracking projects (the first type). + +### Branches, releases, and general development flow + +Master should always be Matter's best branch. Release branches, once cut, are +closed for any feature work. Software fixes for release branches must first land +on master unless demonstrably infeasible. diff --git a/_sources/QUICK_START.md b/_sources/QUICK_START.md new file mode 100644 index 000000000000..74a6532356ab --- /dev/null +++ b/_sources/QUICK_START.md @@ -0,0 +1,52 @@ +# Quick Start + +## Demo Overview + +The Matter reference implementation contains support for a number of examples +and platforms. + +## Wi-Fi Nodes + +|
    Controller / Admin
    |
    Node
    | Description | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [**chip-tool**](https://github.com/project-chip/connectedhomeip/blob/master/examples/chip-tool/README.md) (Linux / Mac)
    Includes docs for all the cluster commands supported
    | **all-clusters-app**
  • [M5Stack](https://github.com/project-chip/connectedhomeip/blob/master/examples/all-clusters-app/esp32/README.md) (ESP)
  • [Linux](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/linux) simulation | Use the command line tool on a laptop to pair with and control an embedded Wi-Fi platform. This demo supports the “all-clusters-app”, so it provides the basic onoff light test and more. | +| [**chip-device-ctrl.py**](https://github.com/project-chip/connectedhomeip/blob/master/src/controller/python/README.md) | **all-clusters-app**
  • [M5Stack](https://github.com/project-chip/connectedhomeip/blob/master/examples/all-clusters-app/esp32/README.md) (ESP)
  • [Linux](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/linux) simulation | Same as above, but uses the pychip tool as Controller Node. | + +## Thread Nodes + +Use one of the controllers listed above and then a Border Router and Node +combination listed below. + +|
    Border Router
    |
    Node
    | Description | +| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [**ot-br**](https://openthread.io/guides/border-router/build)
    Thread Border Router
  • RasPi
  • BeagleBone | **lighting-app**
  • [Nordic nRF5x](https://github.com/project-chip/connectedhomeip/tree/master/examples/lighting-app/nrfconnect/README.md)
  • [NXP K32W](https://github.com/project-chip/connectedhomeip/tree/master/examples/lighting-app/nxp/k32w/k32w0/README.md)
  • [Qorvo QPG6100](https://github.com/project-chip/connectedhomeip/tree/master/examples/lighting-app/qpg)
  • [Silicon Labs EFR32](https://github.com/project-chip/connectedhomeip/tree/master/examples/lighting-app/silabs/README.md) | The Lighting example is supported by many of the available Thread platforms. See the chip-tool controller instructions for how to actuate the light on/off cluster. | +| [**ot-br**](https://openthread.io/guides/border-router/build)
    Thread Border Router
  • RasPi
  • BeagleBone | **lock-app**
  • [Nordic nRF5x](https://github.com/project-chip/connectedhomeip/tree/master/examples/lock-app/nrfconnect/README.md)
  • [NXP K32W](https://github.com/project-chip/connectedhomeip/tree/master/examples/lock-app/nxp/k32w/k32w0/README.md)
  • [Qorvo QPG6100](https://github.com/project-chip/connectedhomeip/tree/master/examples/lock-app/qpg)
  • [Silicon Labs EFR32](https://github.com/project-chip/connectedhomeip/tree/master/examples/lock-app/efr32/README.md)
  • [TI CC13x2x7](https://github.com/project-chip/connectedhomeip/tree/master/examples/lock-app/cc13x2x7_26x2x7/README.md) | The Lock example is supported by many of the available Thread and Wi-Fi platforms. | + +## Controllers + +### chip-tool + +This section summarizes how to run some common scenarios with the +[**chip-tool**](https://github.com/project-chip/connectedhomeip/blob/master/examples/chip-tool/README.md) +controller. + +#### IP Pairing + +`chip-tool pairing onnetwork ${NODE_ID_TO_ASSIGN} 20202021` will use PASE over +IP to commission a device and assign `${NODE_ID_TO_ASSIGN}` (which must be a +decimal number or a 0x-prefixed hex number) as its node id. + +NOTE: On Linux, if the device is actually running after unit tests ran you have +to use `chip-tool pairing onnetwork desired-node-id 34567890`, because the unit +tests change the device configuration. + +NOTE: to run both the Node and Controller as separate processes on the same +Linux or Mac machine, build the all-clusters-app with Bluetooth LE disabled as +follows: + +`scripts/examples/gn_build_example.sh examples/all-clusters-app/linux out/debug/standalone/ chip_config_network_layer_ble=false` + +#### Automated CASE tests + +`chip-tool tests Test_TC_OO_1_1` will run a suite of tests that use CASE To +communicate with a paired `all-clusters-app` peer node. diff --git a/_sources/README.md b/_sources/README.md new file mode 100644 index 000000000000..7d7c889a2f34 --- /dev/null +++ b/_sources/README.md @@ -0,0 +1,228 @@ +# Matter + +[![Builds](https://github.com/project-chip/connectedhomeip/workflows/Builds/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/build.yaml) + +**Builds** + +[![Android](https://github.com/project-chip/connectedhomeip/workflows/Android/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/android.yaml) +[![Ameba](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20Ameba/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-ameba.yaml) +[![ASR](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20ASR/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-asr.yaml) +[![BouffaloLab](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20BouffaloLab/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-bouffalolab.yaml) +[![Darwin](https://github.com/project-chip/connectedhomeip/workflows/Darwin/badge.svg)](https://github.com/project-chip/connectedhomeip/blob/master/.github/workflows/darwin.yaml) +[![TI CC26X2X7](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20TI%20CC13XX_26XX/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-cc13xx_26xx.yaml) +[![TI CC32XX](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20TI%20CC32XX/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-cc32xx.yaml) +[![EFR32](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20EFR32/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-efr32.yaml) +[![ESP32](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20ESP32/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-esp32.yaml) +[![Infineon](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-infineon.yaml/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-infineon.yaml) +[![i.MX Linux](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20i.MX%20Linux/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-linux-imx.yaml) +[![K32W with SE051](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20K32W%20with%20SE051/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-k32w.yaml) +[![Linux ARM](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20Linux%20ARM/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-linux-arm.yaml) +[![Linux Standalone](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20Linux%20Standalone/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-linux-standalone.yaml) +[![Linux Standalone](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20Linux%20Standalone/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-linux-standalone.yaml) +[![Mbed OS](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20Mbed%20OS/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-mbed.yaml) +[![MW320](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20MW320/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-mw320.yaml) +[![nRF Connect SDK](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20nRF%20Connect%20SDK/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-nrfconnect.yaml) +[![Open IoT SDK](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20Open%20IoT%20SDK/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-openiotsdk.yaml) +[![QPG](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20QPG/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-qpg.yaml) +[![STM32](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20stm32/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-stm32.yaml) +[![Telink](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20Telink/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-telink.yaml) +[![Tizen](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20Tizen/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-tizen.yaml) + +**Tests** + +[![Unit / Integration Tests](https://github.com/project-chip/connectedhomeip/workflows/Unit%20/%20Integration%20Tests/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/unit_integration_test.yaml) +[![Cirque](https://github.com/project-chip/connectedhomeip/workflows/Cirque/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/cirque.yaml) +[![QEMU](https://github.com/project-chip/connectedhomeip/workflows/QEMU/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/qemu.yaml) + +**Tools** + +[![ZAP Templates](https://github.com/project-chip/connectedhomeip/workflows/ZAP/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/zap_templates.yaml) + +**Documentation** + +[![Documentation Build](https://github.com/project-chip/connectedhomeip/actions/workflows/docbuild.yaml/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/docbuild.yaml) + +- [Matter SDK documentation page](https://project-chip.github.io/connectedhomeip-doc/index.html) + +# About + +Matter (formerly Project CHIP) creates more connections between more objects, +simplifying development for manufacturers and increasing compatibility for +consumers, guided by the Connectivity Standards Alliance. + +# What is Matter? + +Matter is a unified, open-source application-layer connectivity standard built +to enable developers and device manufacturers to connect and build reliable, and +secure ecosystems and increase compatibility among connected home devices. It is +built with market-proven technologies using Internet Protocol (IP) and is +compatible with Thread and Wi-Fi network transports. Matter was developed by a +Working Group within the Connectivity Standards Alliance (Alliance). This +Working Group develops and promotes the adoption of the Matter standard, a +royalty-free connectivity standard to increase compatibility among smart home +products, with security as a fundamental design tenet. The vision that led major +industry players to come together to build Matter is that smart connectivity +should be simple, reliable, and interoperable. + +Matter simplifies development for manufacturers and increases compatibility for +consumers. + +The standard was built around a shared belief that smart home devices should be +secure, reliable, and seamless to use. By building upon Internet Protocol (IP), +Matter enables communication across smart home devices, mobile apps, and cloud +services and defines a specific set of IP-based networking technologies for +device certification. + +The Matter specification details everything necessary to implement a Matter +application and transport layer stack. It is intended to be used by implementers +as a complete specification. + +The Alliance officially opened the Matter Working Group on January 17, 2020, and +the specification is +[available](https://csa-iot.org/developer-resource/specifications-download-request/) +for adoption now. + +Visit [buildwithmatter.com](https://buildwithmatter.com) to learn more and read +the latest news and updates about the project. + +# Project Overview + +## Development Goals + +Matter is developed with the following goals and principles in mind: + +**Unifying:** Matter is built with and on top of market-tested, existing +technologies. + +**Interoperable:** The specification permits communication between any +Matter-certified device, subject to users’ permission. + +**Secure:** The specification leverages modern security practices and protocols. + +**User Control:** The end user controls authorization for interaction with +devices. + +**Federated:** No single entity serves as a throttle or a single point of +failure for root of trust. + +**Robust:** The set of protocols specifies a complete lifecycle of a device — +starting with the seamless out-of-box experience, through operational protocols, +to device and system management specifications required for proper function in +the presence of change. + +**Low Overhead:** The protocols are practically implementable on low +compute-resource devices, such as MCUs. + +**Pervasive:** The protocols are broadly deployable and accessible, by +leveraging IP and being implementable on low-capability devices. + +**Ecosystem-Flexible:** The protocol is flexible enough to accommodate +deployment in ecosystems with differing policies. + +**Easy to Use:** The protocol provides smooth, cohesive, integrated provisioning +and out-of-box experience. + +**Open:** The Project’s design and technical processes are open and transparent +to the general public, including non-members wherever possible. + +## Architecture Overview + +Matter aims to build a universal IPv6-based communication protocol for smart +home devices. The protocol defines the application layer that will be deployed +on devices and the different link layers to help maintain interoperability. The +following diagram illustrates the normal operational mode of the stack: +![Matter Architecture Overview](images/Matter_Arch_Overview.png) + +The architecture is divided into layers to help separate the different +responsibilities and introduce a good level of encapsulation among the various +pieces of the protocol stack. The vast majority of interactions flow through the +stack captured in the following Figure: + +![Matter Stack Architecture](images/Matter_Layered_Arch.png) + +1. **Application:** High-order business logic of a device. For example, an + application that is focused on lighting might contain logic to handle turning + on/off the bulb as well as its color characteristics. + +2) **Data Model:** The data layer corresponds to the data and verb elements that + help support the functionality of the application. The Application operates + on these data structures when there is an intent to interact with the device. + +3. **Interaction Model:** The Interaction Model layer defines a set of + interactions that can be performed between a client and server device. For + example, reading or writing attributes on a server device would correspond to + application behavior on the device. These interactions operate on the + elements defined at the data model layer. + +4) **Action Framing:** Once an action is constructed using the Interaction + Model, it is serialized into a prescribed packed binary format to encode for + network transmission. + +5. **Security:** An encoded action frame is then sent down to the Security Layer + to encrypt and sign the payload to ensure that data is secured and + authenticated by both sender and receiver of a packet. + +6. **Message Framing & Routing:** With an interaction encrypted and signed, the + Message Layer constructs the payload format with required and optional header + fields; which specify the message's properties and some routing information. + +7) **IP Framing & Transport Management:** After the final payload has been + constructed, it is sent to the underlying transport protocol for IP + management of the data. + +# Current Status of Matter + +Matter’s design and technical processes are intended to be open and transparent +to the general public, including to Working Group non-members wherever possible. +The availability of this GitHub repository and its source code under an Apache +v2 license is an important and demonstrable step to achieving this commitment. +Matter endeavors to bring together the best aspects of market-tested +technologies and redeploy them as a unified and cohesive whole-system solution. +The overall goal of this approach is to bring the benefits of Matter to +consumers and manufacturers as quickly as possible. As a result, what you +observe in this repository is an implementation-first approach to the technical +specification, vetting integrations in practice. The Matter repository is +growing and evolving to implement the overall architecture. The repository +currently contains the security foundations, message framing and dispatch, and +an implementation of the interaction model and data model. The code examples +show simple interactions, and are supported on multiple transports -- Wi-Fi and +Thread -- starting with resource-constrained (i.e., memory, processing) silicon +platforms to help ensure Matter’s scalability. + +# How to Contribute + +We welcome your contributions to Matter. Read our contribution guidelines +[here](https://github.com/project-chip/connectedhomeip/blob/master/CONTRIBUTING.md). + +# Building and Developing in Matter + +Instructions about how to build Matter can be found [here](https://github.com/project-chip/connectedhomeip/blob/master/README.md) . + +# Directory Structure + +The Matter repository is structured as follows: + +| File/Folder | Content | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| build | Build system support content and built output directories | +| build_overrides | Build system parameter customization for different platforms | +| config | Project configurations | +| credentials | Development and test credentials | +| docs | Documentation, including guides. Visit the [Matter SDK documentation page](https://project-chip.github.io/connectedhomeip-doc/index.html) to read it. | +| examples | Example firmware applications that demonstrate use of Matter | +| integrations | 3rd party integrations | +| scripts | Scripts needed to work with the Matter repository | +| src | Implementation of Matter | +| third_party | 3rd party code used by Matter | +| zzz_generated | ZAP generated template code - Revolving around cluster information | +| BUILD.gn | Build file for the GN build system | +| CODE_OF_CONDUCT.md | Code of conduct for Matter and contribution to it | +| CONTRIBUTING.md | Guidelines for contributing to Matter | +| LICENSE | Matter license file | +| REVIEWERS.md | PR reviewers | +| gn_build.sh | Build script for specific projects such as Android, EFR32, etc. | +| README.md | This file | + +# License + +Matter is released under the [Apache 2.0 license](https://github.com/project-chip/connectedhomeip/blob/master/../LICENSE). diff --git a/_sources/VSCODE_DEVELOPMENT.md b/_sources/VSCODE_DEVELOPMENT.md new file mode 100644 index 000000000000..4bb79d380904 --- /dev/null +++ b/_sources/VSCODE_DEVELOPMENT.md @@ -0,0 +1,159 @@ +# Visual Studio Code Development + +[Visual Studio Code](https://code.visualstudio.com/) is a great and simple IDE +that can be used to build & develop with for Matter. + +Matter supports the docker / remote container workflow in Visual Studio Code, +and has a container environment setup automatically. You can read more about +this workflow [here](https://code.visualstudio.com/docs/remote/containers). + +Tested on: + +- macOS 10.5 +- Windows 10 Pro + WSL + Ubuntu 18 LTS +- Linux - Fedora Core 35 distribution + +## Setup Steps + +1. _Windows Only_ Enable the Windows Subsystem for Linux (WSL) following + instructions here: + +1. _Windows Only_ Install Ubuntu from the Windows App Store here: + +1. Install [Docker](https://www.docker.com/) for your operating system of choice + from here: +1. Install [Visual Studio Code](https://code.visualstudio.com/) for your + operating system of choice here: +1. Install [Git](https://git-scm.com/) if you haven't already +1. _Windows Only_ Enable git to use LF instead of CLRF by default: + `git config --global core.autocrlf false` +1. Git clone the main Matter repository here: + +1. Launch Visual Studio Code, and open the cloned folder from above +1. Install the + [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) + extension for Visual Studio Code, this extension allows you to use docker + containers as a development backend. +1. Once this is installed, you'll be prompted to reload Visual Studio Code, do + so +1. At the bottom right of your Visual Studio Code window you should have a new + box prompting you to re-open the window as a container. Hit yes. +1. _Windows Only_ Update your Visual Studio Code settings as documented here: + https://code.visualstudio.com/docs/editor/integrated-terminal#_configuration + to use Bash on Ubuntu (on Windows) eg: + `"terminal.integrated.shell.windows": "C:\\Windows\\System32\\bash.exe"` +1. Now your local machine is building a docker image that has all the tools + necessary to build and test Matter. This can take some time, but will + eventually complete and open up the source tree + +## Bootstrapping your source tree (one time) + +1. Under the "Terminal" menu (or using another shortcut to the same tool), + select "Run Task..." +1. Select the "Bootstrap" task + +## Building the Source Tree + +1. Under the "Terminal" menu select "Run Build Task..." + +## Tasks + +Located in the [tasks json](https://github.com/project-chip/connectedhomeip/blob/master/.vscode/tasks.json) file you'll find a list of +tasks that can be run from the "Run Task..." command. Example tasks are "Clean", +"Run Pretty Check" + +Developers are encouraged to add tasks to the +[tasks json](https://github.com/project-chip/connectedhomeip/blob/master/.vscode/tasks.json) over time to make sure everyone is using the +same base configuration and build. + +### Current base tasks are listed here + +- Main Build - Build the default configuration (i.e., Linux OpenSSL) +- Run Unit and Functional Tests - Test the default configuration +- Build & Test (all) - Build & Test various configurations (Linux variants, + Android, EFR32) +- Update compilation database - Update the database used by IntelliSense + (needed for cross references, completion) +- Bootstrap - On a clean tree, pull in the third party dependencies required +- Clean Output - Remove build artifacts +- Clean Tree - Full (and destructive) git clean of the tree + +## Launch Tasks + +Located in the [launch json](https://github.com/project-chip/connectedhomeip/blob/master/.vscode/launch.json) file you'll find a list of +build & run jobs that can be run from the "Run" tab and start a run or debug +session. + +Developers are encouraged to add tasks to the +[launch json](https://github.com/project-chip/connectedhomeip/blob/master/.vscode/launch.json) over time to make sure everyone is using +the same base debugging setup. + +## Submitting a Pull Request - Practical Advice + +### Before submitting a PR, make sure these commands run and succeed + +- Run task: "Build & Test (all)" + +## Common Issues + +- [Missing Git credential](https://code.visualstudio.com/docs/remote/containers#_sharing-git-credentials-with-your-container) +- [Missing Git SSH keys](https://code.visualstudio.com/docs/remote/containers#_sharing-git-credentials-with-your-container) +- [Using GPG signing keys](https://github.com/microsoft/vscode-remote-release/issues/72) + +## Docker FAQ + +### DNS problem: can't resolve archive.ubuntu.com + +A common problem encountered is that a container can't resolve +`archive.ubuntu.com` and can't install anything via `apt-get`, during the +creation of the container image, resulting in an error like: + +``` +E: Package 'locales' has no installation candidate +The command '/bin/sh -c apt-get install -y locales && localedef -i en_US -c -f UTF-8 -A /usr/share/locale/locale.alias en_US.UTF-8' returned a non-zero code: 100 +``` + +Most common reason for this is that the DNS for docker daemon has not been set +up correctly and is simply using a default: 8.8.8.8, which in many corporate or +more secure environments is not accessible. A typical solution for this is to +put a following key/value into your system-wide docker `daemon.json` (Typically +located under `/etc/docker/daemon.json` on a Linux system): + +``` +"dns": ["<>", "8.8.8.8"] +``` + +You can obtain the address you should put into that line of your nameserver by +running: + +``` +nmcli dev show | grep 'IP4.DNS' +``` + +After you update the dns, you should restart docker, specific to your system. On +a typical Linux workstation, you do this via: + +``` +sudo service docker restart +``` + +Alternatively, you can also pass the `--dns` argument to your docker daemon, but +creating a `daemon.json` and following the above method will solve the problem +system-wide. + +## Visual Studio Code FAQ + +- _Highly_ recommend you read through + [this page](https://code.visualstudio.com/docs/getstarted/settings) to learn + how to configure Visual Studio Code to suit your style: + +- Great primer set of videos + [here](https://code.visualstudio.com/docs/getstarted/introvideos) + + +## Visual Studio Code Recommended Settings + +- Configure the editor to format on save, in your Visual Studio Code Settings: + `"editor.formatOnSave": true` +- Configure the clang-format extension `@ext:xaver.clang-format`, it is + installed in the docker container. Make sure all languages are enabled diff --git a/_sources/api/device_runner.md b/_sources/api/device_runner.md new file mode 100644 index 000000000000..db9c5993eff6 --- /dev/null +++ b/_sources/api/device_runner.md @@ -0,0 +1,103 @@ +# CHIP on-device testing + +_Requirements and high-level design_ + +## Background + +The ability to run tests on actual and emulated hardware is paramount in +embedded projects. CHIP is no exception. We want on-device testing to be a first +class goal of CHIP architecture. On-device testing requirements apply both to +Continuous Integration testing for main CHIP software stack development and to +eventual CHIP product certification. This document explores the requirements and +evaluates potential solutions. + +## Overview of requirements + +A good device test infrastructure is built on four pillars. + +### Pillar 1: Using a test framework + +A test framework provides a testing structure that developers can follow and +potentially reduces some of the burden of test setup and teardown (less +boilerplate). Support for state-oriented and asynchronous structuring of tests +would be beneficial. Many test frameworks leverage scripting languages such as +Python to simplify the quick development of tests and to leverage rich sets of +libraries for device/systems access and results generation. + +### Pillar 2: Dispatching tests + +Tests can run on lab machines or on the developer's local workstation. Tests can +be triggered manually by the developer or as a result of completion of a +changeset built on a continuous integration (CI) server. CHIP involves multiple +stakeholders, many of which will want to contribute to the testing efforts with +lab capacity. The infrastructure therefore must be prepared for +cross-organization test dispatch. + +To facilitate uniform dispatch of tests we will probably need a simple +request/response protocol. Potentially HTTPS based and RESTful. Due to the long +running nature of device tests the response for a test scheduling request could +be a test ID, not the test result. That ID could be used to query the test +status, subscribe for notifications on status changes and to pull the test +results. Core aspects of such a scheme include the conventions for request +artifacts contents and minimum expected results contents once the run is +complete. + +### Pillar 3: Interacting with devices + +The test host environment has to reset devices, flash images on them, issue +commands, monitor status and collect test results. It may also need to integrate +both virtual (simulated) and real devices together. This can at first be done in +an ad-hoc way per platform but eventually we can go into device access +abstraction, i.e. define a common device testing interface which CHIP-compliant +devices can expose. The test host has to be prepared for driving multiple +devices at the same time for a single test, e.g. for tests that check +communication between multiple devices. + +### Pillar 4: Collecting results + +Ideally, test results are output in standard formats and similar or analogous +results between different devices and tests are output the same way. This +ensures reusability of code that processes similar data while allowing +aggregation of results across different dimensions. Failed tests must propagate +errors from device platform layers all the way to the CHIP stack and present +errors and potential stack traces in a standard result format. As the purpose of +on-device tests is to capture bugs, it is important that the test outputs +highlight the failure reason(s) and developers don't have to browse through +thousands of lines of logs to find the one line that sheds light on why a test +failed. + +## Priorities + +In the spirit of CHIP's charter, it would be great to see something taking-off +as soon as possible, to support continuous testing of the evolving CHIP stack. +We could then improve on that first iteration, even if we have to throw away +some temporary concepts and code. + +Test dispatch (Pillar 2) arises as the highest priority, because all other +pillars can have ad-hoc solutions. The first need is an interface between a +CircleCI job and a test execution host at a participating organization. This +would enable dispatching tests to a variety of existing in-house infrastructure, +while retaining common request/response protocols to shield the CI system from +implementation details of each lab. + +The next most important goal is to provide a test framework (Pillar 1). With a +standard framework developers can start writing tests, even if those tests will +be device specific and of ad-hoc input and output format. The general structure +of tests will however be present and later the tests can be adapted to standard +interactions (Pillar 3) and result formats (Pillar 4). + +Specifying result formats (Pillar 4) for the most common outputs +(success/failure, failure reason, stack trace, memory and CPU usage time series, +pcaps of network traffic, etc.) will be an ongoing effort. The simplest output +formats can be specified together with the test framework. + +Lastly, we want to look into a common device interaction interface that would +enable reusing tests between different devices. + +## Baseline hardware platforms for CHIP + +The TSG is targeting the following platforms/boards for early bringup: + +- Nordic nRF52 board +- SiLabs `XXXX` board +- Espressif ESP32 `XXXX` board diff --git a/_sources/api/device_runner_dispatch.md b/_sources/api/device_runner_dispatch.md new file mode 100644 index 000000000000..fff2634b41a3 --- /dev/null +++ b/_sources/api/device_runner_dispatch.md @@ -0,0 +1,183 @@ +# CHIP on-device test dispatch + +This document expands on and provides design for on-device test dispatch. The +CHIP on-device testing document states that dispatching should involve a HTTPS +based RESTful protocol that could be integrated with CircleCI. + +## Definitions + +**Test run**: Tests instantiation on a test host, consisting of host-side test +binaries and test scripts as well as one or more device-side binaries. + +**Test host**: A computing execution environment provided for the purposes of +running tests by a party participating in the scheme. + +## Scope + +The scope of this proposal is to support running tests against a known set of +canonical devices and platforms for the purposes of developing core common code +in the CHIP project GitHub repository. + +This proposal does not preclude a stakeholder running their own tests against +their own hardware or lab in any way they see fit. The goal is merely to provide +a common way for volunteer organizations to register test infrastructure and +dispatch capabilities to be used by the wider CHIP developer community. + +Authentication is not considered strictly part of the test dispatch protocol. +However it is mandated that some form of authentication takes place before any +of the test dispatch operations are issued. Throughout this document it is +assumed that proper authentication and authorization is ensured by the server +hosting the test dispatch service. + +## Objectives + +- **Provide a centralized API** for the dispatching of tests against + potentially distributed lab infrastructure, which CI systems (i.e. CircleCI) + or individual developers may not be directly configured to access. +- **Decouple test execution from the CI environment**, especially for tests + requiring complex setups, such as radio traffic capture. +- **Enable** common adoption of **aligned methodologies** for both + certification-style tests and development-support tests (pre/post-submit + testing in pull requests). + +### Certification or pre-certification tests + +Certification tests are required to have canonical test suite names. + +Here the host side test binaries and scripts are fixed and the device-side +binary can vary by device type. The objective of certification testing is to run +a known fixed set of tests against new and existing devices. Dispatching of +certification tests involves specifying the canonical test suite name and +providing the requisite arguments, such as device-side binary and device type. + +### Development support tests + +Development support test suites are required to have canonical names, but they +may, during execution, check-out the actual test script from a given PR, or from +the artifacts uploaded for the test job. + +The test is executed against a pull request and may target many device types. +Therefore, both host-side and device-side artifacts may vary and have to be +uploaded in the respective argument to test dispatch operation. Dispatching of +development support test suites therefore involves specifying a canonical test +suite name, the PR URL, pre-built artifacts (host side and device-side) and +optional test-specific arguments. + +### Common constraints for dispatch + +In order to support running tests, some common arguments are required to +determine during dispatch whether a given combination of targets can be +supported. + +These constraints include: + +- A canonical device type list to determine whether a target runner has all + the targets needed. (Note that new hardware developers may provide a + non-canonical device type for running their own certification on their own + lab. Canonical device types exist for development support tests.) +- An optional node ID (unique UUID) to force execution on a given registered + infrastructure for test purposes. + +Example of canonical test suite names: + +- RendezVousTest: loads binaries on HW, validates that assumptions about + RendezVous advertising payload are still valid. +- BasicCHIPRegression: loads binaries on HW, validates against regressions on + multiple axes of the test. Potentially runs updated tests scripts from the + PR itself. + +## Aggregator Dispatch Interface API + +We conceptualize an aggregator service where all the tests are sent to be +further dispatched to or pulled by participating infrastructure/lab providers. + +For the prototype phase the aggregator may be the same service that runs tests +as well, i.e. further dispatch/pull/registration may not happen in the +prototype. + +This is the API which CircleCI and individual test developers can use. There may +be other APIs (e.g. administrator API) to the aggregator that provide richer +functionality. For now we don't discuss those. The API for communication between +the aggregator and test labs is to be specified at a later time. + +The goal of decoupling dispatch from execution is to avoid coupling running the +tests to a given lab’s or organization’s infrastructure. The dispatch interface +API provides a separation of concerns of “what to run”/“what happened” versus +“how to run”/“where to run”. + +### Resources and operations + +/available_test_suites - Collection resource, all the canonical test suite +names. + +- GET gets the list of known canonical test suite names + +/dispatch - Collection resource, all the currently running test executions. + +- POST dispatches a new test, returning its URI with the test run identifier + 'job_id'. - Arguments - Canonical Test Suite name e.g. + "CHIP_basic_test_suite" - ZIP file upload of artifacts (device-side and, if + needed, host-side) - Some common required inputs (see section below) - + Test-suite-specific configuration/contents may also be provided for the test + suite executor to use. - Maximum time the client is willing to wait for + results (seconds) - In case of execution timed out, the test job would be + considered FAILED, due to time-out. - Maximum time the client is willing to + wait for test to start (seconds) - In case of time-out to dispatch, the test + job would be considered ABORTED in the results as opposed to FAILED - + Authentication requirements may cause a given requestor to be throttled by + internal logic. + +/status/ - Member resource, an individual test. + +- GET returns the status of the test: scheduled, running, finished, aborted. +- DELETE cancels the test. + +/status//results - Collection resource, all the files resulting from the +test run. + +- GET returns the list of (file_name, file_id) pairs. + - Only mandatory file: + - test_suite_results.json + - Normalized test results, see section below. + +/status//results/ - Member resource, and individual result +file. + +- GET returns the contents of the file. + +### /dispatch arguments + +**test_suite_name**: _Required_. Name of the test suite. + +**host_artifacts**: _Only required for development support tests_. A file (most +likely a ZIP file) corresponding to all the scripts and binaries to be run by +the test host. The test host must be able to unzip, recognize and execute +contents. + +**device_artifacts**: _Required_. A file (most likely a ZIP file) corresponding +to all the binaries to be flashed on the device. The test host must be able to +unzip, recognize and flash contents. + +**timeout_for_results_seconds**: _Required_. The maximum amount of time in +seconds the client is willing to wait for results. After this much time the test +can be killed by the test host. + +**timeout_for_start_seconds**: _Required_. The maximum amount of time in seconds +the client is willing to wait for the test to start. If after dispatch the test +does not start after this much time the test can be descheduled by the +aggregator. + +### test_suite_results.json contents + +TBD. + +### Aggregator-to-lab dispatch API + +TBD. + +### Lab Registration Interface API + +Once agreement on the dispatch API is cemented, the API to register a given +executor with certain tests and devices capabilities can be defined. + +TBD. diff --git a/_sources/api/index.md b/_sources/api/index.md new file mode 100644 index 000000000000..c139642dc4ed --- /dev/null +++ b/_sources/api/index.md @@ -0,0 +1,7 @@ +# API + +```{toctree} +:glob: + +* +``` diff --git a/_sources/ci-cd/index.md b/_sources/ci-cd/index.md new file mode 100644 index 000000000000..e659abb315f8 --- /dev/null +++ b/_sources/ci-cd/index.md @@ -0,0 +1,48 @@ +# CI/CD Documentation + +```{toctree} +:glob: + +tools/* +``` + +## Project Information + +- [Build Guide](../guides/BUILDING.md) +- Sphinx documentation framework + - New directories and individual files must be added to the + [tree](https://github.com/project-chip/connectedhomeip/blob/master/docs/index.md) + - New files under directories must be added to the tree in the index file; + see above. Glob and regular expressions may be used to include all + - The + [documentation page](https://project-chip.github.io/connectedhomeip-doc/) + is the end product + - Links can be relative; links ending in ".md" in the code will be + reflected as ".html" on that page +- Pull Requests + - Built in style and spelling checks must be satisfied + - Larger changes should go through an approval process; reviewers are + automatically added + - Smaller specific changes like ones to this file may be expedited with + the "fast track" label + +Work In Progress + +## Tasks + +- [Issues List](https://github.com/project-chip/connectedhomeip/labels/CI%2FCD%20improvements) + +## Tools + +- [Daily Fail Summary](tools/daily_fail_summary.md) +- Spellcheck + - Uses + [`rojopolis`/spellcheck-github-actions](https://github.com/marketplace/actions/github-spellcheck-action#configuration), + a PySpelling-based spellchecker + - This tool utilizes the definitions in .spellcheck.yml and + .github/`.wordlist.txt` to check all documentation files. + .spellcheck.yml defines the settings while `.wordlist.txt` is a + dictionary of words to skip checking (brand names, technical jargon, + acronyms) + +## General Improvement Ideas diff --git a/_sources/ci-cd/tools/daily_fail_summary.md b/_sources/ci-cd/tools/daily_fail_summary.md new file mode 100644 index 000000000000..8855a7a3de60 --- /dev/null +++ b/_sources/ci-cd/tools/daily_fail_summary.md @@ -0,0 +1,34 @@ +### Daily Fail Summary + +#### Source + +Workflow: +https://github.com/project-chip/connectedhomeip/blob/master/.github/workflows/recent_fail_summary.yaml + +Script: +https://github.com/project-chip/connectedhomeip/blob/master/scripts/tools/summarize_fail.py + +Fail Definitions: +https://github.com/project-chip/connectedhomeip/blob/master/scripts/tools/build_fail_definitions.yaml + +#### Summary + +Runs once per day; takes inventory of the previous day's workflow runs and +parses them for fail statistics. Creates temporarily cached artifacts for easy +data parsing. Also saves a daily pass percentage list of all workflows at +https://github.com/project-chip/connectedhomeip/blob/daily_pass_percentage/docs/daily_pass_percentage.md. +Fail definitions can be added to the file defined above to allow fast root cause +determination of any fail with an error message. + +#### To Do + +- Keep fail signature list updated to track causes of all common fails +- Include Darwin Test fail definitions in fail summary script - for starters, + Test Reliable Message Protocol + +#### Improvement Ideas + +- Make script artifact more known and accessible so it can be easily shared + and used by everyone +- Deliver daily fail summaries in short form through a Slack bot for easy + access diff --git a/_sources/cluster_and_device_type_dev/cluster_and_device_type_dev.md b/_sources/cluster_and_device_type_dev/cluster_and_device_type_dev.md new file mode 100644 index 000000000000..b9471192e608 --- /dev/null +++ b/_sources/cluster_and_device_type_dev/cluster_and_device_type_dev.md @@ -0,0 +1,254 @@ +# New Clusters & Device Types + +The goal of new cluster and device type development is to + +1. write the cluster implementations +2. write the code and supporting material that will allow zap to generate the + appropriate ember layers +3. write the unit tests, test plans and automation scripts that prove the code + correctness and allow these new features to be certified + +Unit tests, test plans and certification tests are covered in the testing +section. This document will concentrate on implementing clusters and device +types in the SDK. + +- Cluster Definition + - XML + - Describes the structures, enums, attributes, commands, events etc. + - Direct translation of the spec into code + - [src/app/zap-templates/zcl/data-model/chip/](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/data-model/chip) +- Cluster Implementation + + - Client side - codegen, you write the glue + - Server side - cpp implementation through Ember and / or + [AttributeAccessInterface](https://github.com/project-chip/connectedhomeip/blob/master/src/app/AttributeAccessInterface.h) + and + [CommandHandlerInterface](https://github.com/project-chip/connectedhomeip/blob/master/src/app/CommandHandlerInterface.h) + - src/app/clusters/ + - build file: + [src/app/chip_data_model.gni](https://github.com/project-chip/connectedhomeip/blob/master/src/app/chip_data_model.gni) + - build file uses data from the codegen to auto-populate the cluster + list. + - Follow examples in there to get your code building into the image + when selected in zap + +- Device Type Definitions + - XML defines conformance + - [src/app/zap-templates/zcl/data-model/chip/matter-devices.xml](https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap-templates/zcl/data-model/chip/matter-devices.xml) + +See [How To Add New Device Types & Clusters](how_to_add_new_dts_and_clusters.md) +for a detailed description of how and where to add cluster and device type +definitions so they are picked up properly by ZAP/ember and the SDK. + +Note that the output should also be verified against the spec using the +[.matter parser tools](https://project-chip.github.io/connectedhomeip-doc/guides/matter_idl_tooling.html). + +## ZAP, Ember and Overrides + +- Goal: get zap to understand the new cluster so it can be used on devices + (XML and glue) + +![](../getting_started/img/zap_compiler.png) + +### Cluster definitions and ZAP + +Please see [ZAP](../getting_started/zap.md) for an introduction to ZAP. + +After implementing the changes outlined in the wiki article, your cluster and +device type should show up in zap. you can check this by running zaptool with +any zap file. + +./scripts/tools/zap/run_zaptool.sh + +To ensure the cluster and device type are correctly implemented for ZAP, open +the endpoint configuration and ensure the device type appears in the device type +list. + +![](../getting_started/img/zap3.png) + +Next, check your cluster. The "domain" parameter in the XML controls which group +the cluster is in. It should have all the expected attributes, commands and +events. + +![](../getting_started/img/zap4.png) + +Last, ensure that your attributes have the storage option set appropriately. + +![](../getting_started/img/zap5.png) + +### Cluster implementation - Ember and overrides + +- Ember: layer used to setup/access the endpoints / attributes / commands etc. + on the device + + - The build generates the Ember function signatures and defaults + - The Cluster server code implements callbacks for initialization, + commands, attribute access and event generation + - Interaction Model layer will call ember functions when it receives + incoming interactions for your cluster + +- Overrides + - Ember layer is _generated_ at compile time whereas overrides are + _installed_ at run time + - Overrides are called before the ember layer for attribute access or + command handling + - AttributeAccessInterface & CommandHandlerInterface + - Allow significantly more control, but are more complex + - **UNIT TESTABLE** + - Both allow fall through to the ember layer (if setup in zap) + +#### Cluster Server Initialization + +The following diagram shows the flow of messages coming into the Matter core and +ending in the cluster initialization code. + +![](img/cluster_initialization.png) + +EmberAfInitializeAttributes - ember attribute storage - for all attributes +marked as “RAM” in the zap, sets defaults in the storage +MatterPluginServerCallback - .h is a generated file, .cpp impl is done +in the server cluster code. Use this to setup the cluster and do attribute +overrides registerAttributeAccessOverride - use this if you want to handle +attribute reads and writes externally + +Blue sections can be overridden. + +#### Cluster Server Attributes + +**Two mechanisms** + +- Ember layer +- Override + +**ZAP files and implementation** + +- For attributes marked as **“RAM”** storage in the zap file + - Storage allocated automatically, Ember handles read/write + - Generated “Get” and “Set” functions for each attribute in Accessors.h + (generated file) + - You _CAN_ register an override on the cluster. If you don’t try to + encode the attribute in the override, it will fall through to the + storage. + - If you _DO_ always encode the attribute in the access override + function, you’re wasting space. +- For attributes marked as **“External”** storage in the zap file + - NO storage is allocated, no fall through to ember storage + - NEED to register an access override for these to work + +##### Cluster Server Attributes via Override (read) + +![](img/cluster_attribute_read.png) + +[AttributeAccessInterface::Read()](https://github.com/project-chip/connectedhomeip/blob/master/src/app/AttributeAccessInterface.h#L424) + +``` +CHIP_ERROR Read(const ConcreteReadAttributePath & aPath, + AttributeValueEncoder & aEncoder) +{ + // Parse aPath to determine the requested attribute + switch (aPath.mAttributeId) + { + case SomeAttribute::Id: + // Just encode the value + aEncoder.Encode(mSomeValue); + break; + } + // Beware of lists - the need to use EncodeList to have + // chunking handled properly + return CHIP_NO_ERROR; +``` + +#### Cluster Server Attributes via override (write) + +Write are handled using the same path as read, but land in the “Write” function +of the AttributeAccessInterface. + +[AttributeAccessInterface::Write()](https://github.com/project-chip/connectedhomeip/blob/master/src/app/AttributeAccessInterface.h#444) + +The attribute handler is responsible for constraint checking and Attribute +persistence + +##### Attribute Persistence + +- When using AttributeAccessInterface, you need to manage any Attributes that + require Persistence. +- This can be done by using GetSafeAttributePersistenceProvider() +- This provides a useful API for Reading & Writing values of any type to the + default Persistence Store + - [src/app/SafeAttributePersistenceProvider.h](https://github.com/project-chip/connectedhomeip/blob/master/src/app/SafeAttributePersistenceProvider.h) + +#### Ember layer read / write + +In the ember layer functions, the ember layer handles the encode and decode. +This can work for simple attributes, but is can be challenging for complex +attribute interactions. The ember layer is also VERY difficult to unit test. + +The ember layer provides callbacks for attribute changes so you can handle them + +``` +void MatterPostAttributeChangeCallback(const chip::app::ConcreteAttributePath & attributePath, + uint8_t type, uint16_t size, uint8_t * value) + +``` + +Take care when using this that the callbacks are implemented in a way that can +be used across examples + +#### Cluster Server Commands + +- As with Attributes, there is an ember layer option, and an override option +- **Override** + - Registered at runtime + - InteractionModelEngine::RegisterCommandHandler + - Implement CommandHandlerInterface +- **Ember** + - static + - emberAfCallback + +![](img/cluster_commands.png) + +##### Command Handler Code + +- [CommandHandlerInterface](https://github.com/project-chip/connectedhomeip/blob/master/src/app/CommandHandlerInterface.h) + - Can use HandleCommand function for convenience (sets handled) + - If not, need to set whether the command was handled + - if no, falls through to ember by default + - If entirely handled by this interface, add to + src/app/common/templates/config-data.yaml to disable ember +- Ember interface + - Return true if the command was handled, false to have an invalid command + response returned +- For both + - Need to handle the return to the caller using either AddResponse or + AddStatus in the command handler + - Need to handle constraints checking and return the appropriate status or + response per the spec + +The +[config-data.yaml](https://github.com/project-chip/connectedhomeip/blob/master/src/app/common/templates/config-data.yaml) +file is used to turn off ember command callback generation for clusters with +pure CommandHandlerInterface implementations. + +#### Events and Attribute Subscriptions + +- **Attribute** change reporting + - If you go through the ember storage layer (generated Get/Set functions + on the attribute), this is handled for you + - If you are using an AttributeAccessInterface, you need to tell the + reporting engine that the attribute has changed + - **MatterReportingAttributeChangeCallback** +- **Events** + - No direct ember support + - Call LogEvent function in EventLogging.h. Caller has to either lock the + Matter stack lock or queue the event to the Matter event queue when + using LogEvent. + +#### A note on Dynamic Endpoints + +- Dynamic endpoint registration + - ZAP configs are static at compile time + - Can also use dynamic endpoint registration at runtime + - common for bridges + - **emberAfSetDynamicEndpoint** + - If you have your own storage for attributes etc, need to account for + dynamic endpoints as well as static diff --git a/_sources/cluster_and_device_type_dev/how_to_add_new_dts_and_clusters.md b/_sources/cluster_and_device_type_dev/how_to_add_new_dts_and_clusters.md new file mode 100644 index 000000000000..3790ebf7b9d2 --- /dev/null +++ b/_sources/cluster_and_device_type_dev/how_to_add_new_dts_and_clusters.md @@ -0,0 +1,248 @@ +# How to Add New Device Types & Clusters + +This document outlines the process needed to add a new Matter device type and +related clusters. Obviously, the steps below assume that the related Matter +specifications were properly reviewed and approved. + +## Add the cluster definitions to the SDK + +The following steps should be followed to add new cluster definitions to the +SDK. + +**Add your new cluster definition to an appropriately-name file in this +directory:** +[src/app/zap-templates/zcl/data-model/chip](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/data-model/chip) + +**Add references to each new cluster definition to these files:** + +1. [.github/workflows/tests.yaml](https://github.com/project-chip/connectedhomeip/tree/master/.github/workflows/tests.yaml) +2. [scripts/rules.matterlint](https://github.com/project-chip/connectedhomeip/tree/master/scripts/rules.matterlint) +3. [src/app/zap-templates/zcl/data-model/all.xml](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/data-model/all.xml) +4. [src/app/zap-templates/zcl/zcl-with-test-extensions.json](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/zcl-with-test-extensions.json) +5. [src/app/zap-templates/zcl/zcl.json](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/zcl.json) +6. If it is a derived cluster, add a reference to the base cluster definition. + (e.g. in mode-base-cluster.xml you may need to add cluster codes - otherwise + you may get strange exceptions which aren't clear when running regen_all.py) + + > ``` + > + > + > + > + > ``` + +7. [src/controller/python/chip/clusters/\_\_init\_\_.py](https://github.com/project-chip/connectedhomeip/tree/master/src/controller/python/chip/clusters/__init__.py) + +**Enable your new cluster in the Python and Android clients** in +[src/controller/data_model/controller-clusters.zap](https://github.com/project-chip/connectedhomeip/blob/master/src/controller/data_model/controller-clusters.zap) + +You will need the ZAP tool to edit the ZAP file. + +- Unless you already have the tool installed, you can use one of the + [nightly builds](https://github.com/project-chip/zap/releases) +- [ZAP tool info](https://developers.home.google.com/matter/tools/zap) +- [ZAP tool repo](https://github.com/project-chip/zap) + +Use the ZAP GUI tool to edit the file above: + +1. From the command line, navigate to the directory containing + [controller-clusters.zap](https://github.com/project-chip/connectedhomeip/blob/master/src/controller/data_model) +2. Run zap: `../../../scripts/tools/zap/run_zaptool.sh controller-clusters.zap`. + Alternatively, run the zap tool and navigate to the zap file that you wish to + open, or run as + `./scripts/tools/zap/run_zaptool.sh src/controller/data_model/controller-clusters.zap`. +3. In the gui, select `Endpoint-1` from the left pane. +4. Open the cluster group, for example, `Appliances`. +5. Find the cluster to be enabled, e.g. `Dishwasher Control`. +6. In the Enable column, select "Client" from the drop-down box. +7. Click `File->Save` to save the configuration. +8. Close the GUI. + +**Add entries for your new cluster to +[BUILD.gn](https://github.com/project-chip/connectedhomeip/blob/master/cluster_and_device_type_dev/c/src/controller/data_model/BUILD.gn)** in the outputs section of the +java-jni-generate bits. The entries should look like +"jni/YourClusterNameClient-InvokeSubscribeImpl.cpp" and +"jni/YourClusterNameClient-ReadImpl.cpp". + +**Add an entry to the ClientDirectories** section of +[src/app/zap_cluster_list.json](https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap_cluster_list.json). + +**Update `chip-tool`** + +1. Regenerate all zap generated code using `./scripts/tools/zap_regen_all.py` +2. Rebuild chip-tool and it will have new cluster support: + `./scripts/examples/gn_build_example.sh examples/chip-tool SOME-PATH/` + +## Add the device type definition to the SDK + +1. Add the XML definition of the device to + [matter-devices.xml](https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap-templates/zcl/data-model/chip/matter-devices.xml) +2. Implement the incoming command behaviors common to all applications. The + parsing of the payload from TLV to a C++ struct is done by code + auto-generated from the XML (see + [zap-generated](https://github.com/project-chip/connectedhomeip/blob/master/zzz_generated/app-common/app-common/zap-generated)) + The rest of the functionality must be manually implemented. Note: for the + auto-generated code run one of the following: + 1. for everything: `./scripts/tools/zap_regen_all.py` + 2. just for the app-common part: + `./scripts/tools/zap/generate.py -t src/app/common/templates/templates.json -o zzz_generated/app-common/app-common/zap-generated src/controller/data_model/controller-clusters.zap` +3. Implement the read/write/storage operations for the attributes of any type, + list, or struct which are not the global attributes present in all clusters. + For example, there's no need to implement CommandList, AttributeList etc. For + the attributes which are not list of struct type, the handling code is + implemented generically so most likely no work is needed for them. +4. Implement any attribute spec requirements that are common to all + applications. For example: code to enforce specific ranges, code for handling + the interactions between attributes etc. + +## Implement Code and Tests + +Implement the clusters, the example cluster server application and add the +related SDK tests. + +1. Implement new clusters here: + [src/app/clusters](https://github.com/project-chip/connectedhomeip/tree/master/src/app/clusters) +2. Implement tests here: + [src/app/tests/suites](https://github.com/project-chip/connectedhomeip/tree/master/src/app/tests/suites) +3. Implement the example cluster server application: + 1. The YAML tests will run against this server + 2. Depending on the clusters, there are two options: + 1. Enable them in the all-clusters-app and use that as the example + cluster server app. If choosing this option, consider adding an + example application that has just the relevant clusters enabled; this + part is a nice to have. + 2. If the clusters have complicated global application requirements + consider using a separate example app. see the door lock, bridge, TV, + OTA clusters. + 3. NOTES: If adding a new cluster derived from `mode-base` into + [examples/all-clusters-app/](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/) + (Assume your new cluster is called `XZYMode`): + 1. Create your new `xyz-mode-cluster.xml` in + [src/app/zap-templates/zcl/data-model/chip](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/data-model/chip) + (as above). Note that this is a much cut down cluster definition + compared to normal clusters, since it derives from + [mode-base-cluster.xml](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/data-model/chip/mode-base-cluster.xml). + See + [dishwasher-mode-cluster.xml](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/data-model/chip/dishwasher-mode-cluster.xml) + as an example. Note you should review if you need the `StartUpMode` + and `OnMode` attributes based on the spec. + 2. Check that you have added your cluster code into + [mode-base-cluster.xml](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/data-model/chip/mode-base-cluster.xml) + 1. ` ` - replace + `XXXX` with your cluster ID + 2. ` ` - + replace `XXXX` with your cluster ID + 3. ` ` - + replace `XXXX` with your cluster ID + 3. Add your new Mode definitions in `xyz-mode.h`. In this header you + define the modes / labels and tags. See + [dishwasher-mode.h](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/all-clusters-common/include/dishwasher-mode.h) + as an example. + 4. Add your new stub to instantiate the mode. See + [dishwasher-mode.cpp](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/all-clusters-common/src/dishwasher-mode.cpp) + as an example. + 5. In + [examples/all-clusters-app/linux/main-common.cpp](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/linux/main-common.cpp): + 1. Add `#include "xyz-mode.h"` + 2. In `ApplicationShutdown()`, add a call to your + `Clusters::XYZMode::Shutdown();`. + 6. In + [examples/all-clusters-app/linux/BUILD.gn](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/linux/BUILD.gn), + add the `xyz-mode.cpp` file to the `sources` section. + 7. In + [src/app/common/templates/config-data.yaml](https://github.com/project-chip/connectedhomeip/blob/master/src/app/common/templates/config-data.yaml): + 1. Add a `::ModeTag` to the `EnumsNotUsedAsTypeInXML` + section. + 2. Add an `XYZ Mode` entry to the + `CommandHandlerInterfaceOnlyClusters` section. + 8. In + [src/app/util/util.cpp](https://github.com/project-chip/connectedhomeip/blob/master/src/app/util/util.cpp), + in the `// Cluster Init Functions...` section, add a void + `MatterXYZModePluginServerInitCallback() {}` definition. + 9. In + [src/app/zap-templates/zcl/zcl-with-test-extensions.json](https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap-templates/zcl/zcl-with-test-extensions.json): + 1. Add the `xyz-mode-cluster.xml` to the `xmlFile` list + 2. In the `attributeAccessInterfaceAttributes` entry, add your new + entry + `"XYZ Mode": [ "SupportedModes", "CurrentMode", "FeatureMap" ]` - + this will mean ZAP won't generate code to handle these attributes + 10. In + [src/app/zap_cluster_list.json](https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap_cluster_list.json): + 1. Add your `XYZ_MODE_CLUSTER: []` to `ClientDirectories: { }` + object + 2. Add your `"XYZ_MODE_CLUSTER": ["mode-base-server"]` to + `"ServerDirectories": { }` + 4. The code under + [src/app/tests/suites/certification](https://github.com/project-chip/connectedhomeip/blob/master/src/app/tests/suites/certification) + for YAML or + [src/python_testing](https://github.com/project-chip/connectedhomeip/tree/master/src/python_testing) + for Python should ideally implement the test plan (section 4 below). + 5. A test under + [src/app/tests/suites](https://github.com/project-chip/connectedhomeip/blob/master/src/app/tests/suites) + (not certification) can test anything, in addition to, or preceding the + official YAML representing the official test plan. +4. Add the test plan, using the templates below: + + 1. [cluster_test_plan_template.adoc](https://github.com/CHIP-Specifications/chip-test-plans/blob/master/src/template/cluster_test_plan_template.adoc) + 2. [test_plan_template.adoc](https://github.com/CHIP-Specifications/chip-test-plans/blob/master/src/template/test_plan_template.adoc) + + Also, ask to be added to the private `csg-tt-test-plans` Slack channel. + +5. Note: the CHIP-Tool reference client is generated from XML +6. If applicable, add tests: + 1. For relatively simple tests, add YAML tests here: + [src/app/tests/suites/certification](https://github.com/project-chip/connectedhomeip/blob/master/src/app/tests/suites/certification). + Remember to update this file: + [src/app/tests/suites/certification/PICS.yaml](https://github.com/project-chip/connectedhomeip/blob/master/src/app/tests/suites/certification/PICS.yaml) + 2. For more complex tests, add Python tests here: + [src/python_testing](https://github.com/project-chip/connectedhomeip/tree/master/src/python_testing) + 3. To add tests to CI, if applicable: + 1. Add the Python tests here: + [.github/workflows/tests.yaml](https://github.com/project-chip/connectedhomeip/tree/master/.github/workflows/tests.yaml). + Remember to provide all arguments required for each Python script, + such as the endpoint PIXIT. + 2. Add the YAML tests by editing this file: + [src/app/tests/suites/ciTests.json](https://github.com/project-chip/connectedhomeip/tree/master/src/app/tests/suites/ciTests.json) + 1. Create a section ("MyDevice") which lists all YAML tests for your + device + 2. Add the section's name to the list of items named "collection" + 3. Do a ZAP code regen: `./scripts/tools/zap_regen_all.py`. +7. Add the device type spec to the test plan tools: + + 1. [tools/device_type_requirements](https://github.com/CHIP-Specifications/chip-test-plans/tree/master/tools/device_type_requirements) + 2. The file above is used by + [src/app/tests/suites/certification/Test_TC_DESC_2_1.yaml](https://github.com/project-chip/connectedhomeip/blob/master/src/app/tests/suites/certification/Test_TC_DESC_2_1.yaml) + + Note: the plan is to make the DM tools generate the device type requirements + data based on the spec, so the above will become obsolete. + +8. Add the device type to Chef: + [examples/chef/devices](https://github.com/project-chip/connectedhomeip/tree/master/examples/chef/devices) + +## Q & A + +**Q1**: What kind of devices can be used for the test events? Can one of them be +the example cluster server app running on a RasPI? Do the independent +realizations need to run on vendor hardware or can they also run on generic +hardware, such as ESP32 or RasPI? + +**A1**: one realization can be the test harness + the all clusters example app + +RasPI. the two independent realizations need to run on target hardware, which +may be mock-ups, prototypes etc + +**Q2**: How can the Chef tool be used for any of the deliverables above? + +**A2**: TBD + +**Q3**: What is the process for using the Zap tool in order to auto-generate +code and to commit the results to the git repo? + +**A3**: Search for zap_regen above. Add all the changed files to the repo after. + +**Q4**: Where can the older cluster definitions be found? + +**A4**: src/app/zap-templates/zcl/data-model/silabs/general.xml + +**Q5**: Where can I find ZAP documentation? + +**A5**: https://github.com/project-chip/zap/blob/master/README.md diff --git a/_sources/cluster_and_device_type_dev/index.md b/_sources/cluster_and_device_type_dev/index.md new file mode 100644 index 000000000000..df952c69d5f3 --- /dev/null +++ b/_sources/cluster_and_device_type_dev/index.md @@ -0,0 +1,16 @@ +# Cluster and Device Type development + +The following docs present a guide on how to develop new clusters and device +types in the SDK. + +```{toctree} +:glob: +:maxdepth: 1 +:hidden: + +* + +``` + +- [Cluster and device type development](./cluster_and_device_type_dev.md) +- [How To Add New Device Types & Clusters](how_to_add_new_dts_and_clusters.md) diff --git a/_sources/code_generation.md b/_sources/code_generation.md new file mode 100644 index 000000000000..3b79f5e4be68 --- /dev/null +++ b/_sources/code_generation.md @@ -0,0 +1,355 @@ +# Code generation + +## Code generation inputs (`*.zap` files) + +Matter code relies on code generation for cluster-specific data types and +callbacks. Generally this is split into: + +- Data serialization for structures/lists/commands. This applies to both + client-side and server-side structures and objects +- Callback setup using the Ember-based framework. This generally applies to + server-side processing and the code generation defines what processing needs + to be done when a specific command is received or an attribute is read and + what memory should be allocated for storing cluster attributes + +Code generation depends on the clusters that are needed by an application. Every +application configures the specific set of endpoints and clusters it needs based +on the device type it supports. The selection of the supported clusters and +attributes (as optional attributes may be omitted to save memory) is generally +stored in `*.zap` files. + +The selection of enabled clusters and files is done using +[ZAP](https://github.com/project-chip/zap). You can download a recent release of +zap from its [releases page](https://github.com/project-chip/zap/releases). It +is recommended to download a release that is in sync with the currently in use +version by the SDK (see `scripts/setup/zap.json` and +`scripts/tools/zap/zap_execution.py` for the minimum supported version). + +Beyond basic zap file selection, there are also `.json` zap settings that define +additional cluster info: source XML files, sdk-access methods and data types. +There are only two such files currently in use: + +- `src/app/zap-templates/zcl/zcl.json` is the **default** one +- `src/app/zap-templates/zcl/zcl-with-test-extensions.json` is used by + `all-clusters-app` to show how a cluster extension may be configured with + minimal changes from `zcl.json` (but it is different) + +### Installing zap and environment variables + +ZAP is generally installed as a third-party tool via CIPD during the build +environment bootstrap (see `scripts/setup/zap.json`), which makes `zap-cli` +available in `$PATH` when running in a build environment. + +When matter scripts need to invoke `zap-cli` (for code generation) or `zap` (to +start the UI tool), they make use of the following environment variables to +figure out where the zap tool is located (in order of precedence): + +- if `$ZAP_DEVELOPMENT_PATH` is set, code assumes you are running zap from + source. Use this if you develop zap. Zap has to be bootstrapped (generally + `npm ci` but check zap documentation for this. Some scripts have a + `--run-bootstrap` command line argument to do this for you) + +- if `$ZAP_INSTALL_PATH` is set, code assumes that `zap` or `zap-cli` is + available in the given path. This is generally an unpacked release. + +- otherwise, scripts will assume `zap`/`zap-cli` is in `$PATH` (this is the + case when running in a bootstrapped environment) + +### Using a UI to edit `.zap` files + +Generally you need to invoke zap with appropriate zcl and generate arguments. +Most of code generation is app specific, so you generally want something of the +form +`--gen src/app/zap-templates/app-templates.json --zcl $ZCL_JSON_FILE $ZAP_FILE_TO_EDIT` + +Since this is tedious to type, the SDK provides a +`scripts/tools/zap/run_zaptool.sh` script to automate this: + +```bash +# Ensure zap is in $PATH or set $ZAP_INSTALL_PATH or $ZAP_DEVELOPMENT_PATH +./scripts/tools/zap/run_zaptool.sh examples/lighting-app/lighting-common/lighting-app.zap +``` + +### Human-readable code generation inputs (`*.matter`) + +`.zap` files are large json files that are generally not human readable. As a +result, the Matter SDK also keeps an equivalent `*.matter` file along side +`.zap` files that contain the same data as `.zap` files, targeted specifically +for matter: + +- They are designed to be human readable, looking like a IDL (think protobuf + or android `aidl`, thrift idl etc.) + +- We strive to make them contain only Matter-specific data (`.zap` files + contain more generic data and is designed to be ZigBee backwards compatible) + +Currently `.matter` files are generated from `.zap` files during the application +specific codegen. + +### `*.matter` parsing and codegen + +`*.matter` files are both human and machine readable. Code that can process +these files is available at `scripts/py_matter_idl` and `scripts/codegen.py`. +You can read the +[scripts/py_matter_idl/matter_idl/README.md](https://github.com/project-chip/connectedhomeip/blob/master/scripts/py_matter_idl/matter_idl/README.md) +for details of how things work. + +`scripts/codegen.py` can generate various outputs based on an input `*.matter` +file. + +The split between `.zap` and `.matter` currently exists as an experiment of code +generation technologies. Currently `.matter`-based Python code generation: + +- has fewer third party dependencies than `zap`, which installs a significant + number of `npm` packages. +- runs significantly faster than zap +- offers more flexible code generation (can generate multiple files per + cluster for example, without which some compiles would run out of RAM on + large compilations) +- has a more flexible templating language +- has human readable (and potentially editable) input +- is more easily provable deterministic (`zap` uses an underlying sqlite + database and some legacy assumptions from zigbee have historically caused + non-determinism) +- uses a synchronous processing model which is potentially easier to develop + for +- has lower complexity, is unit tested and uses typing extensively + +Ideally, the project would be to have a single code generation method in the +long term that has all the benefits and none of the drawbacks. We are not there +yet, however we likely want: + +- Flexible codegen (we will need to split output by clusters or other rules) +- Human-readable inputs that enable code reviews and audits +- Rules that a script can validate based on CSA data model (ensure mandatory + attribute settings are followed, ensure proper device type adherence, ensure + correct cluster and data type definitions) +- Easy to maintain and develop for chosen languages/templates/codegen in + general + +## Code generation outputs and templates + +Code that is generated: + +- **Application-specific**: + + - ZAP generation is based on `.zap` files in `examples/` and generates + server-side processing data: what cluster callbacks to set up, what RAM + to reserve for attribute storage etc. + + - `Codegen.py` will also generate a subset of application-specific files + +- **Automated tests**: embedded client-side tools (`chip-tool` and + `darwin-framework-tool`) generate test-definition data. Each use their own + `examples/${TOOL}/templates/tests/templates.json` to drive what gets + generated. + +- **Controller clusters** target: the file + `src/controller/data_model/controller-clusters.zap` contains a set of + cluster selections to which all applications would potentially have access. + These are generally used as `all clusters selection` and the intent is to + allow any application to access any cluster as a `client side`. + + Client/controllers will codegen based on this, like **tools**, **tests**, + **java**, **python** etc. + +## Running codegen + +### ZAP file generation + +Generating all possible code (all categories above) using zap tool can be done +via: + +```bash +./scripts/tools/zap_regen_all.py +``` + +This can be slow (several minutes). The regen tool allows selection of only +tests so that yaml test development goes faster. + +```bash +./scripts/tools/zap_regen_all.py --type tests +./scripts/tools/zap_regen_all.py --type tests --tests chip-tool +``` + +Additionally, individual code regeneration can be done using +`./scripts/tools/zap/generate.py`: + +```bash +/scripts/tools/zap/generate.py \ + examples/bridge-app/bridge-common/bridge-app.zap +``` + +The above will just generate a `.matter` file along side the `.zap` file, +as this is the only file that requires updates for applications. You can code +generate other things by passing in the `-t/--templates` argument to +generate.py. In those cases, you may also need to specify an output directory +via `-o/--output-dir`. + +#### Flow for updating an application zap file: + +``` +# use zap UI to edit the file (or edit zap file in any other way) +./scripts/tools/zap/run_zaptool.sh $PATH_TO_ZAP_FILE + +# re-generate .matter file. Note that for .matter file generation, output +# directory is NOT used +./scripts/tools/zap/generate.py $PATH_TO_ZAP_FILE +``` + +### Compile-time code generation / pre-generated code + +A subset of code generation (both `codegen.py` and `zap-cli`) is done at compile +time or can use pre-generated output (based on gn/cmake arguments) + +Rules for how `generate.py`/`codegen.py` is invoked at compile time are defined +at: + +- `src/app/chip_data_model.cmake` +- `src/app/chip_data_model.gni` + +Additionally, `build/chip/esp32/esp32_codegen.cmake` adds processing support for +the 2-pass cmake builds used by the Espressif `idf.py` build system. + +## Pre-generation + +Code pre-generation can be used: + +- when compile-time code generation is not desirable. This may be for + importing into build systems that do not have the pre-requisites to run code + generation at build time or to save the code generation time at the expense + of running code generation for every possible zap/generation type +- To check changes in generated code across versions, beyond the comparisons + of golden image tests in `scripts/py_matter_idl/matter_idl/tests` + +The script to trigger code pre-generation is `scripts/codepregen.py` and +requires the pre-generation output directory as an argument + +```bash +scripts/codepregen.py ${OUTPUT_DIRECTORY:-./zzz_pregenerated/} + +# To generate a single output you can use `--input-glob`: + +scripts/codepregen.py --input-glob "*all-clusters*" --input-glob "*controller*" ${OUTPUT_DIRECTORY:-./zzz_pregenerated/} +``` + +### External applications/zap files + +#### Ensure you have a `.matter` file + +Code generation generally will use both `.zap` or `.matter` files. If you only +have a `.zap` file, you can create the corresponding `.matter` file via: + +```bash +scripts/tools/zap/generate.py ${ZAP_FILE_PATH} +``` + +The above will use the template `src/app/zap-templates/matter-idl.json` to +generate a `.matter` file corresponding to the input `.zap` file. + +`.matter` files are designed to be human readable. It is recommended to take a +look at the generated file and see if it contains what is expected and also lint +it. If anything seems wrong, the `.zap` file should be fixed (`.matter` +represents the content of `.zap`). To lint use: + +```bash +scripts/idl_lint.py ${MATTER_FILE_PATH} +``` + +#### Running pre-generation + +If you have zap files outside the CHIP repository (i.e. not in `src` or +`examples`) you should provide the root of your application source. + +```bash +scripts/codepregen.py --external-root ${PATH_TO_SOURCE_ROOT} ${OUTPUT_DIRECTORY:-./zzz_pregenerated/} +``` + +NOTE: `$PATH_TO_SOURCE_ROOT` should be a top-level directory containing +zap/matter files as the code pre-generation will generate files based on the +path inside the root: + +- if files are `$PATH_TO_SOURCE_ROOT/some/path/foo.zap` this will generate + files into `$OUTPUT_DIRECTORY/some/path/foo/...` + +### Using pre-generated code + +Instead of generating code at compile time, the chip build system accepts usage +of a pre-generated folder. It assumes the structure that `codepregen.py` +creates. To invoke use: + +- `build_examples.py` builds accept `--pregen-dir` as an argument, such as: + + ```shell + ./scripts/build/build_examples.py --target $TARGET --pregen-dir $PREGEN_DIR build + ``` + +- `gn` builds allow setting `chip_code_pre_generated_directory` as an + argument, such as: + + ```shell + gn gen --check --fail-on-unused-args --args='chip_code_pre_generated_directory="/some/pregen/dir"' + ``` + +- `cmake` builds allow setting `CHIP_CODEGEN_PREGEN_DIR` variable (which will + get propagated to the underlying `gn` builds as needed), such as: + + ```shell + + west build --cmake-only \ + -d /workspace/out/nrf-nrf5340dk-light \ + -b nrf5340dk_nrf5340_cpuapp \ + /workspace/examples/lighting-app/nrfconnect + -- -DCHIP_CODEGEN_PREGEN_DIR=/some/pregen/dir + + idf.py -C examples/all-clusters-app/esp32 \ + -B /workspace/out/esp32-m5stack-all-clusters \ + -DCHIP_CODEGEN_PREGEN_DIR=/some/pregen/dir \ + reconfigure + + cmake -S /workspace/examples/lighting-app/mbed \ + -B /workspace/out/mbed-cy8cproto_062_4343w-light \ + -GNinja \ + -DMBED_OS_PATH=/workspace/third_party/mbed-os/repo \ + -DMBED_OS_PATH=/workspace/third_party/mbed-os/repo \ + -DMBED_OS_POSIX_SOCKET_PATH=/workspace/third_party/mbed-os-posix-socket/repo \ + -DCHIP_CODEGEN_PREGEN_DIR=/some/pregen/dir + ``` + +### Code generation unit testing + +Code generation is assumed stable between builds and the build system aims to +detect changes in code gen using golden image tests. + +#### `codegen.py` tests + +These tests run against golden inputs/outputs from `scripts/idl/tests`. + +`available_tests.yaml` contains the full list of expected generators and outputs +and the test is run via `test_generators.py`. Use the environment variable +`IDL_GOLDEN_REGENERATE` to force golden image replacement during running of +`ninja check`: + +```shell +IDL_GOLDEN_REGENERATE=1 ninja check +``` + +#### `generate.py` tests + +These tests run against golden inputs/outputs from `scripts/tools/zap/tests`. + +`available_tests.yaml` contains the full list of expected generators and outputs +and the test is run via `scripts/tools/zap/test_generate.py`. Use the +environment variable `ZAP_GENERATE_GOLDEN_REGENERATE` to force golden image +replacement during running of `ninja check`. + +```shell +ZAP_GENERATE_GOLDEN_REGENERATE=1 ninja check +``` + +Alternatively, the golden image can also be re-generated by running the +stand-alone test in a bootstrapped environment: + +```shell +./scripts/tools/zap/test_generate.py --output out/gen --regenerate +``` diff --git a/_sources/data_model/README.md b/_sources/data_model/README.md new file mode 100644 index 000000000000..83f0037572cc --- /dev/null +++ b/_sources/data_model/README.md @@ -0,0 +1,31 @@ +--- +orphan: true +--- + +## Contents + +This folder contains a machine-readable representation of matter clusters. + +The XML files inside `clusters` are generated by a `scraper` script out of the +original specification `AsciiDoc` files. + +## How to update + +The matter specification is not currently public. As such, as script exists to +update the spec XML files, however this is not done automatically. + +You will require access to the following tools locally: + +- `scraper`. A binary copy generally available + [here](https://github.com/csa-data-model/projects/tree/main/DM-Editor/bin/scrape) +- Specification repository checkout from + https://github.com/CHIP-Specifications/connectedhomeip-spec + +Example usage: + +```sh +./scripts/spec_xml/generate_spec_xml.py \ + --scraper ~/Downloads/scrape-adoc-linux \ + --spec-root ~/work/connectedhomeip-spec \ + --output-dir data_model +``` diff --git a/_sources/discussion/index.md b/_sources/discussion/index.md new file mode 100644 index 000000000000..fac1ccb91498 --- /dev/null +++ b/_sources/discussion/index.md @@ -0,0 +1,7 @@ +# Discussion + +```{toctree} +:glob: + +* +``` diff --git a/_sources/discussion/lwip_ipv6.md b/_sources/discussion/lwip_ipv6.md new file mode 100644 index 000000000000..674be43e227a --- /dev/null +++ b/_sources/discussion/lwip_ipv6.md @@ -0,0 +1,143 @@ +# LwIP changes for Matter + +LwIP is one of the network layers used in the Matter platform. Although it has +some good IPv6 support, there are areas that are lacking that we should +implement for Matter. The recommendations here are listed roughly from most to +least important. + +## Route Information Options (RIO) + +The specification requires devices to store route options from Route Information +Options (RIO) sent in router advertisements. This functionality is not currently +present in upstream LwIP. The patch to add this is relatively small, but we may +need to upstream this in order to require its use in Matter. Platforms would +need to incorporate this into their own middleware + +### Recommendation: + +- write a RIO patch, upstream to lwip + - Ensure patch is RFC compliant (especially re: expiry) +- UPDATE: Patch is available at https://savannah.nongnu.org/patch/?10114 + +## Address Scopes + +Link local addresses are less common on IPv4, which normally rely on NAT at the +router to do address translation. Matter mandates the use of IPv6 link local +addresses for communication to nodes on the same network (wifi or thread). When +there is more than one netif in the system (ex. loopback, softAP, STA), the link +local address needs more information to determine which link the address is +local to. This is normally added as the link local scope and can be seen on +addresses ex. `FE80::xxxx:xxxx:xxxx:xxxx%`, where the identifies +the netif (something like `%wlan0` or `%eno1` etc.). + +Without this indicator, the link local address can only be resolved if there is +one netif. LwIP will also allow a direct address match to the netif source +address, but this does not scale well at all and is VERY racy. LwIP also +supports output to a specific netif, but this is not brought up to the socket +layer. + +Upstream LwIP has support for IPv6 address scopes, but only as an option. +However, the code to support this is not present in the CHIP LwIP codebase. +Other platform versions assume this option is not present (ex. M5 has an +assertion on ip address sizes that disallow the use of a scope tag). + +### Recommendation: + +- Ensure Matter SDK code works with scopes on our various platforms OR + alternate: bring netif sendto up through the api / sockets layers +- Audit Matter code to ensure LL addresses are properly scoped to their netif + in all areas (DNS returned addresses especially) + +## Duplicate address detection + +The DAD in LwIP is actually implemented correctly right now, but there are +routers that incorrectly implement multicast for IPv6 and send packets back to +the sender. This triggers the LwIP DAD because it doesn’t check the source. This +can be fixed in the wifi layer as a filter, but it’s easy enough to add the fix +into the LwIP layer. This would help implementers so they don’t all have to +debug the same issues. Recommendation: + +- Create an LwIP patch to check NS/NA packets for source and discard if they + originate from the same device. Upstream and offer patch to vendors. + +## Timers, including TCP + +lwIP uses on-demand timers for IGMP and MLD (see +https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/lwip.html#esp-lwip-custom-modifications +for changes Espressif made to lwIP to help power usage on ESP32 and better +support IPv6), and also has several uncorrelated always-on timers for TCP. These +timers have caused power issues on some products. + +### Recommendation: + +- Make sure to take-in Espressif improvements to timers (not sure they are + upstreamed) +- Look into supporting aligned TCP timers to aggregate multiple timers within + a single wake + +## pbuf management + +Pool-based management has been a source of problems on several products, but +does have advantages over purely “heap” based allocation of pbufs as done in +ESP32 and many common lwIP stacks. + +Overall, having the ability to instrument all PBUF allocations for usage (e.g. +Driver TX, Driver RX, Manual PacketBuffer allocation, internal TCP stack pbufs, +etc) would allow us to move towards a pool approach by allowing us to track the +following: Understanding of the overall memory usage of lwIP packet buffers over +time, helping debug issues related to out-of-pbuf or overly-long queuing. Keep +track of incoming packets dwelling and outgoing packets dwelling to start +dropping at ingress when running out of memory Overall, allow sizing of heap and +pools based on usage patterns. + +### Recommendation: + +- Upstream a portable version of pbuf alloc/free accounting, allowing + registration of instrumentation handlers. +- Add support to account for high watermark of pbuf memory used and concurrent + pbuf allocations. +- Add more pbuf allocation types to allow finer-grained recording of “reason” + for a pbuf alloc + +## IPv6 Ping + +Although ping is not required for Matter, it is very helpful for debugging +networking issues. Having a reliable ping would be beneficial for a lot of +developers. + +LwIP will automatically respond to pings, but has no built-in way to send them. +The current ping implementation is a contrib app that only works for IPv4. +Extending the app is challenging for two reasons: 1) IPv6 checksum needs access +to the pbuf for calculation, which the app doesn’t have and 2) IPv6 has a lot +more ICMP traffic for SLAAC that the app would have to be updated to disregard. +Instead, it might be better to build this into the ICMP layer itself. + +### Recommendation: + +- Add an ASYNC send_icmp6_ping function and add a hook to check ping + responses. Upstream patch if possible. OR write an external ICMP6 ping util + +## DNS + +LwIP's DNS handling isn’t great and breaks down when the router supports +IPv4/IPv6. There is a single list of DNS servers, DHCP, SLAAC and DHCPv6 all +update the list without locks. Basically, whatever wrote to the list last gets +to set the list. Although there is handling for IP type (requesting A or `AAAA` +records), there isn’t handling to specify an IPv6 or IPv4 server specifically, +which can be challenging since not all servers serve all record types. + +The design of the weave connectivity manager moves the DNS selection to the +upper layers by stopping lwip from directly changing the DNS list and hooking to +the DNS selection. This means the DNS selection policy isn’t hard-coded into the +lwip layer. This seems like a good model for CHIP going forward. + +Additionally, we should ensure that CHIP uses non-blocking DNS APIs. + +### Recommendation: + +- bug fix for DHCPv6 to avoid it setting bad addresses. + - note - fixed in + https://git.savannah.nongnu.org/cgit/lwip.git/commit/?id=941300c21c45a4dbf1c074b29a9ca3c88c9f6553, + but not yet released as a part of an official release. +- Create a patch to add hooks to the SetDns and GetDns functions so logic for + selecting the DNS server can be moved into the manager layer diff --git a/_sources/examples/air-purifier-app/air-purifier-common/README.md b/_sources/examples/air-purifier-app/air-purifier-common/README.md new file mode 100644 index 000000000000..2ed26cacf9a2 --- /dev/null +++ b/_sources/examples/air-purifier-app/air-purifier-common/README.md @@ -0,0 +1,353 @@ +# CHIP Air Purifier Example + +This example implements the following PICS: + +``` +# Fan Control +FAN.S=1 +FAN.C=0 +FAN.S.F00=1 +FAN.S.F01=1 +FAN.S.F02=1 +FAN.S.F03=1 +FAN.S.F04=1 +FAN.S.F05=1 +FAN.S.A0000=1 +FAN.S.A0001=1 +FAN.S.A0002=1 +FAN.S.A0003=1 +FAN.S.A0004=1 +FAN.S.A0005=1 +FAN.S.A0006=1 +FAN.S.A0007=1 +FAN.S.A0008=1 +FAN.S.A0009=1 +FAN.S.A000A=1 +FAN.S.A000B=1 +FAN.S.C00.Rsp=1 + +# HEPA Filter Monitoring Cluster +HEPAFREMON.S=1 +HEPAFREMON.C=0 +HEPAFREMON.S.F00=1 +HEPAFREMON.S.F01=1 +HEPAFREMON.S.F02=1 +HEPAFREMON.S.A0000=1 +HEPAFREMON.S.A0001=1 +HEPAFREMON.S.A0002=1 +HEPAFREMON.S.A0003=1 +HEPAFREMON.S.A0004=1 +HEPAFREMON.S.A0005=1 +HEPAFREMON.S.C00.Rsp=1 + +# Activated Carbon Filter Monitoring Cluster +ACFREMON.S=1 +ACFREMON.C=0 +ACFREMON.S.F00=1 +ACFREMON.S.F01=1 +ACFREMON.S.F02=1 +ACFREMON.S.A0000=1 +ACFREMON.S.A0001=1 +ACFREMON.S.A0002=1 +ACFREMON.S.A0003=1 +ACFREMON.S.A0004=1 +ACFREMON.S.A0005=1 +ACFREMON.S.C00.Rsp=1 + +# Air Quality Cluster +AIRQUAL.C=0 +AIRQUAL.S=1 +AIRQUAL.S.F00=1 +AIRQUAL.S.F01=1 +AIRQUAL.S.F02=1 +AIRQUAL.S.F03=1 +AIRQUAL.S.A0000=1 +AIRQUAL.M.AirQualityChange=0 + +# Concentration Measurement CLusters +CDOCONC.C=0 +CDOCONC.S=1 +CDOCONC.S.F00=1 +CDOCONC.S.F01=1 +CDOCONC.S.F02=1 +CDOCONC.S.F03=1 +CDOCONC.S.F04=1 +CDOCONC.S.F05=1 +CDOCONC.S.A0000=1 +CDOCONC.S.A0001=1 +CDOCONC.S.A0002=1 +CDOCONC.S.A0003=1 +CDOCONC.S.A0004=1 +CDOCONC.S.A0005=1 +CDOCONC.S.A0006=1 +CDOCONC.S.A0007=1 +CDOCONC.S.A0008=1 +CDOCONC.S.A0009=1 +CDOCONC.S.A000a=1 + +CMOCONC.C=0 +CMOCONC.S=1 +CMOCONC.S.F00=1 +CMOCONC.S.F01=1 +CMOCONC.S.F02=1 +CMOCONC.S.F03=1 +CMOCONC.S.F04=1 +CMOCONC.S.F05=1 +CMOCONC.S.A0000=1 +CMOCONC.S.A0001=1 +CMOCONC.S.A0002=1 +CMOCONC.S.A0003=1 +CMOCONC.S.A0004=1 +CMOCONC.S.A0005=1 +CMOCONC.S.A0006=1 +CMOCONC.S.A0007=1 +CMOCONC.S.A0008=1 +CMOCONC.S.A0009=1 +CMOCONC.S.A000a=1 + +NDOCONC.C=0 +NDOCONC.S=1 +NDOCONC.S.F00=1 +NDOCONC.S.F01=1 +NDOCONC.S.F02=1 +NDOCONC.S.F03=1 +NDOCONC.S.F04=1 +NDOCONC.S.F05=1 +NDOCONC.S.A0000=1 +NDOCONC.S.A0001=1 +NDOCONC.S.A0002=1 +NDOCONC.S.A0003=1 +NDOCONC.S.A0004=1 +NDOCONC.S.A0005=1 +NDOCONC.S.A0006=1 +NDOCONC.S.A0007=1 +NDOCONC.S.A0008=1 +NDOCONC.S.A0009=1 +NDOCONC.S.A000a=1 + +OZCONC.C=0 +OZCONC.S=1 +OZCONC.S.F00=1 +OZCONC.S.F01=1 +OZCONC.S.F02=1 +OZCONC.S.F03=1 +OZCONC.S.F04=1 +OZCONC.S.F05=1 +OZCONC.S.A0000=1 +OZCONC.S.A0001=1 +OZCONC.S.A0002=1 +OZCONC.S.A0003=1 +OZCONC.S.A0004=1 +OZCONC.S.A0005=1 +OZCONC.S.A0006=1 +OZCONC.S.A0007=1 +OZCONC.S.A0008=1 +OZCONC.S.A0009=1 +OZCONC.S.A000a=1 + +PMICONC.C=0 +PMICONC.S=1 +PMICONC.S.F00=1 +PMICONC.S.F01=1 +PMICONC.S.F02=1 +PMICONC.S.F03=1 +PMICONC.S.F04=1 +PMICONC.S.F05=1 +PMICONC.S.A0000=1 +PMICONC.S.A0001=1 +PMICONC.S.A0002=1 +PMICONC.S.A0003=1 +PMICONC.S.A0004=1 +PMICONC.S.A0005=1 +PMICONC.S.A0006=1 +PMICONC.S.A0007=1 +PMICONC.S.A0008=1 +PMICONC.S.A0009=1 +PMICONC.S.A000a=1 + +FLDCONC.C=0 +FLDCONC.S=1 +FLDCONC.S.F00=1 +FLDCONC.S.F01=1 +FLDCONC.S.F02=1 +FLDCONC.S.F03=1 +FLDCONC.S.F04=1 +FLDCONC.S.F05=1 +FLDCONC.S.A0000=1 +FLDCONC.S.A0001=1 +FLDCONC.S.A0002=1 +FLDCONC.S.A0003=1 +FLDCONC.S.A0004=1 +FLDCONC.S.A0005=1 +FLDCONC.S.A0006=1 +FLDCONC.S.A0007=1 +FLDCONC.S.A0008=1 +FLDCONC.S.A0009=1 +FLDCONC.S.A000a=1 + +PMHCONC.C=0 +PMHCONC.S=1 +PMHCONC.S.F00=1 +PMHCONC.S.F01=1 +PMHCONC.S.F02=1 +PMHCONC.S.F03=1 +PMHCONC.S.F04=1 +PMHCONC.S.F05=1 +PMHCONC.S.A0000=1 +PMHCONC.S.A0001=1 +PMHCONC.S.A0002=1 +PMHCONC.S.A0003=1 +PMHCONC.S.A0004=1 +PMHCONC.S.A0005=1 +PMHCONC.S.A0006=1 +PMHCONC.S.A0007=1 +PMHCONC.S.A0008=1 +PMHCONC.S.A0009=1 +PMHCONC.S.A000a=1 + +PMKCONC.C=0 +PMKCONC.S=1 +PMKCONC.S.F00=1 +PMKCONC.S.F01=1 +PMKCONC.S.F02=1 +PMKCONC.S.F03=1 +PMKCONC.S.F04=1 +PMKCONC.S.F05=1 +PMKCONC.S.A0000=1 +PMKCONC.S.A0001=1 +PMKCONC.S.A0002=1 +PMKCONC.S.A0003=1 +PMKCONC.S.A0004=1 +PMKCONC.S.A0005=1 +PMKCONC.S.A0006=1 +PMKCONC.S.A0007=1 +PMKCONC.S.A0008=1 +PMKCONC.S.A0009=1 +PMKCONC.S.A000a=1 + +TVOCCONC.C=0 +TVOCCONC.S=1 +TVOCCONC.S.F00=1 +TVOCCONC.S.F01=1 +TVOCCONC.S.F02=1 +TVOCCONC.S.F03=1 +TVOCCONC.S.F04=1 +TVOCCONC.S.F05=1 +TVOCCONC.S.A0000=1 +TVOCCONC.S.A0001=1 +TVOCCONC.S.A0002=1 +TVOCCONC.S.A0003=1 +TVOCCONC.S.A0004=1 +TVOCCONC.S.A0005=1 +TVOCCONC.S.A0006=1 +TVOCCONC.S.A0007=1 +TVOCCONC.S.A0008=1 +TVOCCONC.S.A0009=1 +TVOCCONC.S.A000a=1 + +RNCONC.C=0 +RNCONC.S=1 +RNCONC.S.F00=1 +RNCONC.S.F01=1 +RNCONC.S.F02=1 +RNCONC.S.F03=1 +RNCONC.S.F04=1 +RNCONC.S.F05=1 +RNCONC.S.A0000=1 +RNCONC.S.A0001=1 +RNCONC.S.A0002=1 +RNCONC.S.A0003=1 +RNCONC.S.A0004=1 +RNCONC.S.A0005=1 +RNCONC.S.A0006=1 +RNCONC.S.A0007=1 +RNCONC.S.A0008=1 +RNCONC.S.A0009=1 +RNCONC.S.A000a=1 + +# Temperature Measurement Cluster +TMP.S=1 +TMP.S.A0000=1 +TMP.S.A0001=1 +TMP.S.A0002=1 +TMP.S.A0003=1 +TMP.M.ManuallyControlled=0 + +# Relative Humidity Cluster +RH.S=1 +RH.S.A0000=1 +RH.S.A0001=1 +RH.S.A0002=1 +RH.S.A0003=1 +RH.M.ManuallyControlled=0 + +# Thermostat Cluster +TSTAT.S = 1 +TSTAT.S.F00 = 1 +TSTAT.S.F01 = 0 +TSTAT.S.F02 = 0 +TSTAT.S.F03 = 0 +TSTAT.S.F04 = 0 +TSTAT.S.F05 = 0 +TSTAT.S.F06 = 0 + +TSTAT.S.A0000 = 1 +TSTAT.S.A0001 = 0 +TSTAT.S.A0002 = 0 +TSTAT.S.A0003 = 1 +TSTAT.S.A0004 = 1 +TSTAT.S.A0005 = 0 +TSTAT.S.A0006 = 0 +TSTAT.S.A0007 = 0 +TSTAT.S.A0008 = 0 +TSTAT.S.A0009 = 0 +TSTAT.S.A0010 = 0 +TSTAT.S.A0011 = 0 +TSTAT.S.A0012 = 1 +TSTAT.S.A0013 = 0 +TSTAT.S.A0014 = 0 +TSTAT.S.A0015 = 0 +TSTAT.S.A0016 = 0 +TSTAT.S.A0017 = 0 +TSTAT.S.A0018 = 0 +TSTAT.S.A0019 = 0 +TSTAT.S.A001a = 0 +TSTAT.S.A001b = 1 +TSTAT.S.A001c = 1 +TSTAT.S.A001d = 0 +TSTAT.S.A001e = 0 +TSTAT.S.A0020 = 0 +TSTAT.S.A0021 = 0 +TSTAT.S.A0022 = 0 +TSTAT.S.A0023 = 0 +TSTAT.S.A0024 = 0 +TSTAT.S.A0025 = 0 +TSTAT.S.A0029 = 1 +TSTAT.S.A0030 = 0 +TSTAT.S.A0031 = 0 +TSTAT.S.A0032 = 0 +TSTAT.S.A0034 = 0 +TSTAT.S.A0035 = 0 +TSTAT.S.A0036 = 0 +TSTAT.S.A0037 = 0 +TSTAT.S.A0038 = 0 +TSTAT.S.A0039 = 0 +TSTAT.S.A003a = 0 +TSTAT.S.A0040 = 0 +TSTAT.S.A0041 = 0 +TSTAT.S.A0042 = 0 +TSTAT.S.A0043 = 0 +TSTAT.S.A0044 = 0 +TSTAT.S.A0045 = 0 +TSTAT.S.A0046 = 0 +TSTAT.S.A0047 = 0 +TSTAT.S.M.MinSetpointDeadBandWritable = 0 +TSTAT.S.M.HVACSystemTypeConfigurationWritable = 0 + +# Server Commands +TSTAT.S.C00.Rsp = 1 +TSTAT.S.C01.Rsp = 0 +TSTAT.S.C02.Rsp = 0 +TSTAT.S.C03.Rsp = 0 +TSTAT.S.C04.Rsp = 0 +``` diff --git a/_sources/examples/air-purifier-app/ameba/README.md b/_sources/examples/air-purifier-app/ameba/README.md new file mode 100644 index 000000000000..871356891fe7 --- /dev/null +++ b/_sources/examples/air-purifier-app/ameba/README.md @@ -0,0 +1,118 @@ +# CHIP Ameba Air Purifier Example + +This example demonstrates the Matter air purifier application on Ameba platform. + +--- + +- [CHIP Ameba Air Purifier Example](#chip-ameba-air-purifier-example) + - [Supported Device](#supported-device) + - [Building the Example Application](#building-the-example-application) + - [Commissioning](#commissioning) + - [BLE mode](#ble-mode) + - [IP mode](#ip-mode) + - [Cluster Control](#cluster-control) + +--- + +## Supported Device + +The CHIP demo application is supported on +[Ameba RTL8722DM Board](https://www.amebaiot.com/en/amebad). + +## Building the Example Application + +- Check out the Ameba repository in the same folder/directory as the Matter + SDK repository: + +``` +git clone https://github.com/ambiot/ambd_matter.git +``` + +- Setup build environment: + +``` +$ cd connectedhomeip +$ source scripts/bootstrap.sh +``` + +- To build the demo application: + +``` +$ cd ambd_matter/project/realtek_amebaD_va0_example/GCC-RELEASE/project_lp/ +$ make all + +$ cd ambd_matter/project/realtek_amebaD_va0_example/GCC-RELEASE/project_hp/ +$ make -C asdk air_purifier + +From the same directory: +$ make all +``` + +- Combine the three output images for flashing using the **Ameba Image Tool**: + +``` +$ cd ambd_matter/tools/AmebaD/Image_Tool_Linux + +$ sudo ./AmebaD_ImageTool -combine \ + ../../../project/realtek_amebaD_va0_example/GCC-RELEASE/project_lp/asdk/image/km0_boot_all.bin 0x0000 \ + ../../../project/realtek_amebaD_va0_example/GCC-RELEASE/project_hp/asdk/image/km4_boot_all.bin 0x4000 \ + ../../../project/realtek_amebaD_va0_example/GCC-RELEASE/project_hp/asdk/image/km0_km4_image2.bin 0x6000 +``` + +- This will produce a combined Image_All.bin file alongside the image tool + that can be flashed using the **Ameba Image Tool**: + +1. Connect your device via USB +2. Edit the `ambd_matter/tools/AmebaD/mpp.ini` file with the correct port + setting (the rest of the settings should be correct) +3. Click **Download** button and the **Reset** button to get the board into + serial download mode +4. Flash on the image: + +``` +$ cd ambd_matter/tools/AmebaD/Image_Tool_Linux +$ ./AmebaD_ImageTool -download +``` + +## Commissioning + +There are two commissioning modes supported by Ameba platform: + +### BLE mode + +1. Build and Flash +2. The example will run automatically after booting the Ameba board. +3. Test with + [Chip-Tool](https://github.com/project-chip/connectedhomeip/tree/master/examples/chip-tool) + +### IP mode + +1. Build and Flash +2. The example will run automatically after booting the Ameba board. +3. Connect to AP using `ATW0, ATW1, ATWC` commands +4. Test with + [Chip-Tool](https://github.com/project-chip/connectedhomeip/tree/master/examples/chip-tool) + +## Cluster Control + +After successful commissioning, the air purifier clusters can be read and +controlled using +[Chip-Tool](https://github.com/project-chip/connectedhomeip/tree/master/examples/chip-tool#using-the-client-to-send-matter-commands). + +The Air Purifier is a composed device. The example has endpoints configured as +follows: + +- Air purifier on endpoint 1 +- Air quality sensor on endpoint 2 +- Temperature sensor on endpoint 3 +- Relative humidity sensor on endpoint 4 +- Thermostat on endpoint 5 + +Example commands using the chip tool: + +``` +$ ./chip-tool fancontrol write speed-setting 10 ${NODE_ID_TO_ASSIGN} 1 +$ ./chip-tool formaldehydeconcentrationmeasurement read level-value ${NODE_ID_TO_ASSIGN} 2 +$ ./chip-tool temperaturemeasurement read measured-value ${NODE_ID_TO_ASSIGN} 3 +$ ./chip-tool relativehumiditymeasurement read measured-value ${NODE_ID_TO_ASSIGN} 4 +``` diff --git a/_sources/examples/air-purifier-app/cc32xx/README.md b/_sources/examples/air-purifier-app/cc32xx/README.md new file mode 100644 index 000000000000..4fa0a9845ce3 --- /dev/null +++ b/_sources/examples/air-purifier-app/cc32xx/README.md @@ -0,0 +1,163 @@ +# Matter `CC32XXSF` Air Purifier Example Application + +An example application showing the use of [Matter][matter] on the Texas +Instruments CC32XX family of Wireless MCUs. + +--- + +- [Matter `CC32XXSF` Air Purifier Example Application](#matter-cc32xxsf-air-purifier-example-application) + - [Introduction](#introduction) + - [Device UI](#device-ui) + - [Building](#building) + - [Preparation](#preparation) + - [Compilation](#compilation) + - [Adding DAC Certificates](#adding-dac-certificates) + - [Programming](#programming) + - [Code Composer Studio](#code-composer-studio) + - [Viewing Logging Output](#viewing-logging-output) + - [Running the Example](#running-the-example) + - [Provisioning](#provisioning) + - [Bluetooth LE Provisioning](#bluetooth-le-provisioning) + +--- + +## Introduction + +The CC32XX air purifier example application provides a working demonstration of +a connected air purifier device. This uses the open-source CHIP implementation +and the Texas Instruments SimpleLink™ Wi-Fi® CC32xx software development kit. + +By default this example targets the [CC3235SF_LAUNCHXL][cc3235sf_launchxl] +LaunchPad, but the example application is enabled to build on the whole `CC32XX` +family of MCUs. + +The air purifier example is intended to serve both as a means to explore the +workings of CHIP, as well as a template for creating real products based on the +Texas Instruments devices. + +## Device UI + +The left button (`BTN-1`) is used to enable provisioning (provisioning is +enabled as "oneshot" by default). The right button (`BTN-2`) long press is used +to reset the device. + +## Building + +### Preparation + +Some initial setup is necessary for preparing the build environment. This +section will need to be done when migrating to new versions of the SDK. This +guide assumes that the environment is linux based, and recommends Ubuntu 20.04. + +- Download and install [SysConfig][sysconfig] ([recommended + version][sysconfig_recommended]). This can be done simply with the following + commands. + + ``` + $ cd ~ + $ wget https://software-dl.ti.com/ccs/esd/sysconfig/sysconfig-1.13.0_2553-setup.run + $ chmod +x sysconfig-1.13.0_2553-setup.run + $ ./sysconfig-1.13.0_2553-setup.run + ``` + +- Run the bootstrap script to setup the build environment. + + ``` + $ cd ~/connectedhomeip + $ source ./scripts/bootstrap.sh + ``` + +### Compilation + +It is necessary to activate the environment in every new shell. Then run GN and +Ninja to build the executable. + +- Activate the build environment with the repository activate script. + + ``` + $ cd ~/connectedhomeip + $ source ./scripts/activate.sh + ``` + +- Run the build to produce a default executable. By default on Linux the + Sysconfig is located in a `ti` folder in the user's home directory, and you + must provide the absolute path for it. For example + `/home/username/ti/sysconfig_1.13.0`. On Windows the default directory is + `C:\ti`. Take note of this install path, as it will be used in the next + step. + + ``` + $ cd ~/connectedhomeip/examples/air-purifier-app/cc32xx + $ gn gen out/debug --args="ti_sysconfig_root=\"$HOME/ti/sysconfig_1.13.0\"" + $ ninja -C out/debug + ``` + +## Adding DAC Certificates + +To add custom DAC Certificates, the `CC32XXDeviceAttestationCreds.cpp` file in +`examples/platform/cc32xx` can be modified. The private key, public key, DAC +cert and PAI cert arrays all need to be replaced. + +## Programming + +Loading the built image onto a LaunchPad is supported through Code Composer +Studio (CCS). Code Composer Studio can be used to load the image and debug the +source code. UniFlash programming (bin) image is not generated currently. + +### Code Composer Studio + +Programming with CCS will allow for a full debug environment within the IDE. +This is accomplished by creating a target connection to the XDS110 debugger and +starting a project-less debug session. The CCS IDE will attempt to find the +source files on the local machine based on the debug information embedded within +the ELF. CCS may prompt you to find the source code if the image was built on +another machine or the source code is located in a different location than is +recorded within the ELF. + +Download and install [Code Composer Studio][ccs]. + +First open CCS and create a new workspace. + +Create a target connection (sometimes called the CCXML) for your target SoC and +debugger as described in the [Manual Method][ccs_manual_method] section of the +CCS User's Guide. + +Next initiate a project-less debug session as described in the [Manual +Launch][ccs_manual_launch] section of the CCS User's Guide. + +CCS should switch to the debug view described in the [After +Launch][ccs_after_launch] section of the User's Guide. The SoC core will likely +be disconnected and symbols will not be loaded. Connect to the core as described +in the [Debug View][ccs_debug_view] section of the User's Guide. Once the core +is connected, use the `Load` button on the toolbar to load the ELF image. + +Note that the default configuration of the CCXML uses 2-wire cJTAG instead of +the full 4-wire JTAG connection to match the default jumper configuration of the +LaunchPad. + +## Viewing Logging Output + +By default the log output will be sent to the Application/User UART. Open a +terminal emulator to that port to see the output with the following options: + +| Parameter | Value | +| ------------ | -------- | +| Speed (baud) | `115200` | +| Data bits | `8` | +| Stop bits | `1` | +| Parity | `None` | +| Flow control | `None` | + +## Running the Example + +### Provisioning + +The first step to bring the Matter device onto the network is to provision it. +The example accomplishes this through the proprietary SimpleLink provisioning +method (AP or Smart Config) using the SimpleLink Starter Pro mobile app. Once +the device is connected to the local AP, commissioning can be triggered using +"OnNetwork" configuration. + +#### Bluetooth LE Provisioning + +BLE provisioning is not supported currently. diff --git a/_sources/examples/air-purifier-app/linux/README.md b/_sources/examples/air-purifier-app/linux/README.md new file mode 100644 index 000000000000..d050edf0cde1 --- /dev/null +++ b/_sources/examples/air-purifier-app/linux/README.md @@ -0,0 +1,111 @@ +# CHIP Linux Air Purifier Example + +An example showing the use of CHIP on the Linux. The document will describe how +to build and run CHIP Air Purifier Example on A Linux System. This doc is tested +on **Ubuntu 20.04 LTS**. + +The Air Purifier example demonstrates a fully functional Matter Air Purifier +which is a composed device with Endpoint 1 being the Air Purifier. Endpoint 2 is +an Air Quality Sensor, Endpoint 3 is a Relative Humidity Sensor, Endpoint 4 is a +Temperature Sensor and Endpoint 5 is a Thermostat. + +To cross-compile this example on x64 host and run on **NXP i.MX 8M Mini** +**EVK**, see the associated +[README document](../../../guides/nxp/nxp_imx8m_linux_examples.md) for +details. + +
    + +- [CHIP Linux Air Purifier Example](#chip-linux-air-purifier-example) + - [Building](#building) + - [Commandline arguments](#commandline-arguments) + - [Running the Complete Example on Raspberry Pi 4](#running-the-complete-example-on-raspberry-pi-4) + +
    + +## Building + +- Install tool chain + + $ sudo apt-get install git gcc g++ python pkg-config libssl-dev libdbus-1-dev libglib2.0-dev ninja-build python3-venv python3-dev unzip + +- Build the example application: + + $ cd ~/connectedhomeip/examples/air-purifier-app/linux/ + $ git submodule update --init + $ source third_party/connectedhomeip/scripts/activate.sh + $ gn gen out/debug + $ ninja -C out/debug + +- To delete generated executable, libraries and object files use: + + $ cd ~/connectedhomeip/examples/air-purifier-app/linux/ + $ rm -rf out/ + +## Commandline arguments + +- `--wifi` + + Enables WiFi management feature. Required for WiFi commissioning. + +- `--thread` + + Enables Thread management feature, requires ot-br-posix dbus daemon running. + Required for Thread commissioning. + +- `--ble-device ` + + Use specific bluetooth interface for BLE advertisement and connections. + + `interface id`: the number after `hci` when listing BLE interfaces by + `hciconfig` command, for example, `--ble-device 1` means using `hci1` + interface. Default: `0`. + +## Running the Complete Example on Raspberry Pi 4 + +> If you want to test Echo protocol, please enable Echo handler +> +> gn gen out/debug --args='chip_app_use_echo=true' +> ninja -C out/debug + +- Prerequisites + + 1. A Raspberry Pi 4 board + 2. A USB Bluetooth Dongle, Ubuntu desktop will send Bluetooth advertisement, + which will block CHIP from connecting via BLE. On Ubuntu server, you need + to install `pi-bluetooth` via APT. + 3. Ubuntu 20.04 or newer image for ARM64 platform. + +- Building + + Follow [Building](#building) section of this document. + +- Running + + - [Optional] Plug USB Bluetooth dongle + + - Plug USB Bluetooth dongle and find its bluetooth device number. The + number after `hci` is the bluetooth device number, `1` in this + example. + + $ hciconfig + hci1: Type: Primary Bus: USB + BD Address: 00:1A:7D:AA:BB:CC ACL MTU: 310:10 SCO MTU: 64:8 + UP RUNNING PSCAN ISCAN + RX bytes:20942 acl:1023 sco:0 events:1140 errors:0 + TX bytes:16559 acl:1011 sco:0 commands:121 errors:0 + + hci0: Type: Primary Bus: UART + BD Address: B8:27:EB:AA:BB:CC ACL MTU: 1021:8 SCO MTU: 64:1 + UP RUNNING PSCAN ISCAN + RX bytes:8609495 acl:14 sco:0 events:217484 errors:0 + TX bytes:92185 acl:20 sco:0 commands:5259 errors:0 + + - Run Linux Air Purifier Example App + + $ cd ~/connectedhomeip/examples/air-purifier-app/linux + $ sudo out/debug/chip-air-purifier-app --ble-device [bluetooth device number] + # In this example, the device we want to use is hci1 + $ sudo out/debug/chip-air-purifier-app --ble-device 1 + + - Test the device using ChipTool on your laptop / workstation etc. diff --git a/_sources/examples/air-quality-sensor-app/linux/README.md b/_sources/examples/air-quality-sensor-app/linux/README.md new file mode 100644 index 000000000000..f8193146c87c --- /dev/null +++ b/_sources/examples/air-quality-sensor-app/linux/README.md @@ -0,0 +1,194 @@ +# Matter Linux Air Quality Example + +An example showing the use of Matter on the Linux. The document will describe +how to build and run Matter Linux Air Quality Example on Raspberry Pi. This doc +is tested on **Ubuntu for Raspberry Pi Server 20.04 LTS (aarch64)** and **Ubuntu +for Raspberry Pi Desktop 20.10 (aarch64)** + +To cross-compile this example on x64 host and run on **NXP i.MX 8M Mini** +**EVK**, see the associated +[README document](../../../guides/nxp/nxp_imx8m_linux_examples.md) for +details. + +
    + +- [Matter Linux Air Quality Example](#matter-linux-air-quality-example) + - [Building](#building) + - [Commandline Arguments](#commandline-arguments) + - [Running the Complete Example on Raspberry Pi 4](#running-the-complete-example-on-raspberry-pi-4) + - [Trigger event using air-quality-sensor-app event named pipe](#trigger-event-using-air-quality-sensor-app-event-named-pipe) + +
    + +## Building + +- Install tool chain + + $ sudo apt-get install git gcc g++ python pkg-config libssl-dev libdbus-1-dev libglib2.0-dev ninja-build python3-venv python3-dev unzip + +- Build the example application: + + $ cd ~/connectedhomeip/examples/air-quality-sensor-app/linux + $ git submodule update --init + $ source third_party/connectedhomeip/scripts/activate.sh + $ gn gen out/debug + $ ninja -C out/debug + +- To delete generated executable, libraries and object files use: + + $ cd ~/connectedhomeip/examples/air-quality-sensor-app/linux + $ rm -rf out/ + +- Build the example with pigweed RPC + + $ cd ~/connectedhomeip/examples/air-quality-sensor-app/linux + $ git submodule update --init + $ source third_party/connectedhomeip/scripts/activate.sh + $ gn gen out/debug --args='import("//with_pw_rpc.gni")' + $ ninja -C out/debug + +## Commandline arguments + +- `--wifi` + + Enables WiFi management feature. Required for WiFi commissioning. + +- `--thread` + + Enables Thread management feature, requires ot-br-posix dbus daemon running. + Required for Thread commissioning. + +- `--ble-device ` + + Use specific bluetooth interface for BLE advertisement and connections. + + `interface id`: the number after `hci` when listing BLE interfaces by + `hciconfig` command, for example, `--ble-device 1` means using `hci1` + interface. Default: `0`. + +## Running the Complete Example on Raspberry Pi 4 + +> gn gen out/debug +> ninja -C out/debug + +- Prerequisites + + 1. A Raspberry Pi 4 board + 2. A USB Bluetooth Dongle, Ubuntu desktop will send Bluetooth advertisement, + which will block Matter from connecting via BLE. On Ubuntu server, you + need to install `pi-bluetooth` via APT. + 3. Ubuntu 20.04 or newer image for ARM64 platform. + +- Building + + Follow [Building](#building) section of this document. + +- Running + + - [Optional] Plug USB Bluetooth dongle + + - Plug USB Bluetooth dongle and find its bluetooth device number. The + number after `hci` is the bluetooth device number, `1` in this + example. + + $ hciconfig + hci1: Type: Primary Bus: USB + BD Address: 00:1A:7D:AA:BB:CC ACL MTU: 310:10 SCO MTU: 64:8 + UP RUNNING PSCAN ISCAN + RX bytes:20942 acl:1023 sco:0 events:1140 errors:0 + TX bytes:16559 acl:1011 sco:0 commands:121 errors:0 + + hci0: Type: Primary Bus: UART + BD Address: B8:27:EB:AA:BB:CC ACL MTU: 1021:8 SCO MTU: 64:1 + UP RUNNING PSCAN ISCAN + RX bytes:8609495 acl:14 sco:0 events:217484 errors:0 + TX bytes:92185 acl:20 sco:0 commands:5259 errors:0 + + - Run Linux Air Quality Example App + + $ cd ~/connectedhomeip/examples/air-quality-sensor-app/linux + $ sudo out/debug/chip-air-quality-sensor-app --ble-device [bluetooth device number] + # In this example, the device we want to use is hci1 + $ sudo out/debug/chip-air-quality-sensor-app --ble-device 1 + + - Test the device using ChipDeviceController on your laptop / + workstation etc. + +## Trigger event using air-quality-sensor-app event named pipe + +You can send a command to air-quality-sensor-app to trigger specific event via +air-quality-sensor-app event named pipe /tmp/chip_air_quality_fifo\*. + +### Trigger air quality change event + +Generate event `AirQuality`, to change the air quality value. + +``` +$ echo '{"Name":"AirQuality","NewValue":3}' > /tmp/chip_air_quality_fifo_ +``` + +### Trigger Temperature change event + +Generate event `TemperatureMeasurement`, to change the temperate value. + +``` +$ echo '{"Name":"TemperatureMeasurement","NewValue":1800}' > /tmp/chip_air_quality_fifo_ +``` + +### Trigger Humidity change event + +Generate event `RelativeHumidityMeasurement`, to change the relative humidity +value (6000 for 60,0 %). + +``` +$ echo '{"Name":"RelativeHumidityMeasurement","NewValue":6000}' > /tmp/chip_air_quality_fifo_ +``` + +### Trigger concentration change event + +Concentration change events can be trigger on the concentration measurement +clusters. + +Generate event `CarbonDioxideConcentrationMeasurement`, to change the CO2 value. + +``` +$ echo '{"Name":"CarbonDioxideConcentrationMeasurement","NewValue":400}' > /tmp/chip_air_quality_fifo_ +``` + +Generate event `CarbonMonoxideConcentrationMeasurement`, to change the CO value. + +``` +$ echo '{"Name":"CarbonMonoxideConcentrationMeasurement","NewValue":1}' > /tmp/chip_air_quality_fifo_ +``` + +Generate event `NitrogenDioxideConcentrationMeasurement`, to change the NO₂ +value. + +``` +$ echo '{"Name":"NitrogenDioxideConcentrationMeasurement","NewValue":1}' > /tmp/chip_air_quality_fifo_ +``` + +Generate event `Pm1ConcentrationMeasurement`, to change the PM1 value. + +``` +echo '{"Name":"Pm1ConcentrationMeasurement","NewValue":1}' > /tmp/chip_air_quality_fifo_ +``` + +Generate event `Pm25ConcentrationMeasurement`, to change the PM2.5 value. + +``` +echo '{"Name":"Pm25ConcentrationMeasurement","NewValue":2.5}' > /tmp/chip_air_quality_fifo_ +``` + +Generate event `Pm10ConcentrationMeasurement`, to change the PM10 value. + +``` +echo '{"Name":"Pm10ConcentrationMeasurement","NewValue":10}' > /tmp/chip_air_quality_fifo_ +``` + +Generate event `TotalVolatileOrganicCompoundsConcentrationMeasurement`, to +change the TVOC value. + +``` +$ echo '{"Name":"TotalVolatileOrganicCompoundsConcentrationMeasurement","NewValue":100}' > /tmp/chip_air_quality_fifo_ +``` diff --git a/_sources/examples/air-quality-sensor-app/telink/README.md b/_sources/examples/air-quality-sensor-app/telink/README.md new file mode 100644 index 000000000000..1474df190e2d --- /dev/null +++ b/_sources/examples/air-quality-sensor-app/telink/README.md @@ -0,0 +1,179 @@ +# Matter Telink Air Quality Sensor Example Application + +You can use this example as a reference for creating your own application. + +![Telink B91 EVK](http://wiki.telink-semi.cn/wiki/assets/Hardware/B91_Generic_Starter_Kit_Hardware_Guide/connection_chart.png) + +## Build and flash + +1. Run the Docker container: + + ```bash + $ docker run -it --rm -v $PWD:/host -w /host ghcr.io/project-chip/chip-build-telink:$(wget -q -O - https://raw.githubusercontent.com/project-chip/connectedhomeip/master/.github/workflows/examples-telink.yaml 2> /dev/null | grep chip-build-telink | awk -F: '{print $NF}') + ``` + + Compatible docker image version can be found in next file: + + ```bash + $ .github/workflows/examples-telink.yaml + ``` + +2. Activate the build environment: + + ```bash + $ source ./scripts/activate.sh -p all,telink + ``` + +3. In the example dir run (replace __ with your board name, for + example, `tlsr9518adk80d`, `tlsr9528a` or `tlsr9258a`): + + ```bash + $ west build -b + ``` + + Also use key `-DFLASH_SIZE`, if your board has memory size different from 2 + MB, for example, `-DFLASH_SIZE=1m` or `-DFLASH_SIZE=4m`: + + ```bash + $ west build -b tlsr9518adk80d -- -DFLASH_SIZE=4m + ``` + +4. Flash binary: + + ``` + $ west flash --erase + ``` + +## Usage + +### UART + +To get output from device, connect UART to following pins: + +| Name | Pin | +| :--: | :---------------------------- | +| RX | PB3 (pin 17 of J34 connector) | +| TX | PB2 (pin 16 of J34 connector) | +| GND | GND | + +### Buttons + +The following buttons are available on **tlsr9518adk80d** board: + +| Name | Function | Description | +| :------- | :--------------------- | :----------------------------------------------------------------------------------------------------- | +| Button 1 | Factory reset | Perform factory reset to forget currently commissioned Thread network and back to uncommissioned state | +| Button 2 | `AirQuality` control | Manually triggers the `AirQuality` state | +| Button 3 | Thread start | Commission thread with static credentials and enables the Thread on device | +| Button 4 | Open commission window | The button is opening commissioning window to perform commissioning over BLE | + +### LEDs + +#### Indicate current state of Thread network + +**Red** LED indicates current state of Thread network. It is able to be in +following states: + +| State | Description | +| :-------------------------- | :--------------------------------------------------------------------------- | +| Blinks with short pulses | Device is not commissioned to Thread, Thread is disabled | +| Blinks with frequent pulses | Device is commissioned, Thread enabled. Device trying to JOIN thread network | +| Blinks with wide pulses | Device commissioned and joined to thread network as CHILD | + +#### Indicate identify of device + +**Green** LED used to identify the device. The LED starts blinking when the +Identify command of the Identify cluster is received. The command's argument can +be used to specify the the effect. It is able to be in following effects: + +| Effect | Description | +| :------------------------------ | :--------------------------------------------------------------------------- | +| Blinks (200 ms on/200 ms off) | Blink (`Clusters::Identify::EffectIdentifierEnum::kBlink`) | +| Breathe (during 1000 ms) | Breathe (`Clusters::Identify::EffectIdentifierEnum::kBreathe`) | +| Blinks (50 ms on/950 ms off) | Okay (`Clusters::Identify::EffectIdentifierEnum::kOkay`) | +| Blinks (1000 ms on/1000 ms off) | Channel Change ( `Clusters::Identify::EffectIdentifierEnum::kChannelChange`) | +| Blinks (950 ms on/50 ms off) | Finish ( `Clusters::Identify::EffectIdentifierEnum::kFinishEffect`) | +| LED off | Stop (`Clusters::Identify::EffectIdentifierEnum::kStopEffect`) | + +### CHIP tool commands + +1. Build + [chip-tool cli](https://github.com/project-chip/connectedhomeip/blob/master/examples/chip-tool/README.md) + +2. Pair with device + + ``` + ${CHIP_TOOL_DIR}/chip-tool pairing ble-thread ${NODE_ID} hex:${DATASET} ${PIN_CODE} ${DISCRIMINATOR} + ``` + + Example: + + ``` + ./chip-tool pairing ble-thread 1234 hex:0e080000000000010000000300000f35060004001fffe0020811111111222222220708fd61f77bd3df233e051000112233445566778899aabbccddeeff030e4f70656e54687265616444656d6f010212340410445f2b5ca6f2a93a55ce570a70efeecb0c0402a0fff8 20202021 3840 + ``` + +### OTA with Linux OTA Provider + +OTA feature enabled by default only for ota-requestor-app example. To enable OTA +feature for another Telink example: + +- set CONFIG_CHIP_OTA_REQUESTOR=y in corresponding "prj.conf" configuration + file. + +After build application with enabled OTA feature, use next binary files: + +- zephyr.bin - main binary to flash PCB (Use at least 2MB PCB). +- zephyr-ota.bin - binary for OTA Provider + +All binaries has the same SW version. To test OTA “zephyr-ota.bin” should have +higher SW version than base SW. Set CONFIG_CHIP_DEVICE_SOFTWARE_VERSION=2 in +corresponding “prj.conf” configuration file. + +Usage of OTA: + +- Build the [Linux OTA Provider](https://github.com/project-chip/connectedhomeip/blob/master/examples/ota-provider-app/linux) + + ``` + ./scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/ota-provider-app chip_config_network_layer_ble=false + ``` + +- Run the Linux OTA Provider with OTA image. + + ``` + ./chip-ota-provider-app -f zephyr-ota.bin + ``` + +- Provision the Linux OTA Provider using chip-tool + + ``` + ./chip-tool pairing onnetwork ${OTA_PROVIDER_NODE_ID} 20202021 + ``` + + here: + + - \${OTA_PROVIDER_NODE_ID} is the node id of Linux OTA Provider + +- Configure the ACL of the ota-provider-app to allow access + + ``` + ./chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": null}]' ${OTA_PROVIDER_NODE_ID} 0 + ``` + + here: + + - \${OTA_PROVIDER_NODE_ID} is the node id of Linux OTA Provider + +- Use the chip-tool to announce the ota-provider-app to start the OTA process + + ``` + ./chip-tool otasoftwareupdaterequestor announce-otaprovider ${OTA_PROVIDER_NODE_ID} 0 0 0 ${DEVICE_NODE_ID} 0 + ``` + + here: + + - \${OTA_PROVIDER_NODE_ID} is the node id of Linux OTA Provider + - \${DEVICE_NODE_ID} is the node id of paired device + +Once the transfer is complete, OTA requestor sends ApplyUpdateRequest command to +OTA provider for applying the image. Device will restart on successful +application of OTA image. diff --git a/_sources/examples/all-clusters-app/ameba/README.md b/_sources/examples/all-clusters-app/ameba/README.md new file mode 100644 index 000000000000..2fa456d0dec2 --- /dev/null +++ b/_sources/examples/all-clusters-app/ameba/README.md @@ -0,0 +1,191 @@ +# CHIP Ameba All Clusters Example + +A prototype application that demonstrates device commissioning and cluster +control. + +--- + +- [CHIP Ameba All Clusters Example](#chip-ameba-all-clusters-example) + - [Supported Device](#supported-device) + - [Building the Example Application](#building-the-example-application) + - [Commissioning](#commissioning) + - [BLE mode](#ble-mode) + - [IP mode](#ip-mode) + - [Cluster control](#cluster-control) + - [Running RPC Console](#running-rpc-console) + - [Running Matter Shell](#running-matter-shell) + - [Binding and Controlling a Device](#binding-and-controlling-a-device) + +--- + +## Supported Device + +The CHIP demo application is supported on +[Ameba RTL8722DM Board](https://www.amebaiot.com/en/amebad). + +## Building the Example Application + +- Pull docker image: + + $ docker pull ghcr.io/project-chip/chip-build-ameba:47 + +- Run docker container: + + $ docker run -it -v ${CHIP_DIR}:/root/chip ghcr.io/project-chip/chip-build-ameba:47 + +- Setup build environment: + + $ source ./scripts/bootstrap.sh + +- To build the demo application: + + $ ./scripts/build/build_examples.py --target ameba-amebad-all-clusters build + + The output image files are stored in + `out/ameba-amebad-all-clusters/asdk/image` folder. + + The bootloader image files are stored in + `out/ameba-amebad-all-clusters/asdk/bootloader` folder. + +- After building the application, **Ameba Image Tool** is used to flash it to + Ameba board. + +1. Connect your device via USB and open Ameba Image Tool. +2. Select correct serial port and set baudrate as **115200**. +3. Browse and add the corresponding image files in the Flash Download list to + the correct locations +4. Click **Download** button. + +## Commissioning + +There are two commissioning modes supported by Ameba platform: + +### BLE mode + +1. Build and Flash +2. The all-clusters example will run automatically after booting the Ameba + board. +3. Test with + [Chip-Tool](https://github.com/project-chip/connectedhomeip/tree/master/examples/chip-tool) + +### IP mode + +1. Build and Flash +2. The all-clusters example will run automatically after booting the Ameba + board. +3. Connect to AP using `ATW0, ATW1, ATWC` commands +4. Test with + [Chip-Tool](https://github.com/project-chip/connectedhomeip/tree/master/examples/chip-tool) + +## Cluster Control + +After successful commissioning, use the OnOff cluster command to control the +OnOff attribute. This allows you to toggle a parameter implemented by the device +to be On or Off. + +- Via + [Chip-Tool](https://github.com/project-chip/connectedhomeip/tree/master/examples/chip-tool#using-the-client-to-send-matter-commands) + + $ ./chip-tool onoff on 1 + $ ./chip-tool onoff off 1 + +## Running RPC Console + +- Connect a USB-TTL adapter as shown below +- For AmebaD + + Ameba USB-TTL + A19 TX + A18 RX + GND GND + +* For AmebaZ2 + + Ameba USB-TTL + A13 TX + A14 RX + GND GND + +- Build the + [chip-rpc console](https://github.com/project-chip/connectedhomeip/tree/master/examples/common/pigweed/rpc_console) + +- As part of building the example with RPCs enabled the chip_rpc python + interactive console is installed into your venv. The python wheel files are + also created in the output folder: out/debug/chip_rpc_console_wheels. To + install the wheel files without rebuilding: + + $ pip3 install out/debug/chip_rpc_console_wheels/*.whl + +* Launch the chip-rpc console after resetting Ameba board + + $ chip-console --device /dev/tty -b 115200 + +- Get and Set lighting directly using the RPC console + + python + rpcs.chip.rpc.Lighting.Get() + rpcs.chip.rpc.Lighting.Set(on=True, level=128, color=protos.chip.rpc.LightingColor(hue=5, saturation=5)) + +## Running Matter Shell + +- Matter Shell is enabled whenever RPC is disabled. + +- RPC console and Matter Shell cannot be enabled at the same time as they use + the same UART port. + +- Connect Ameba to the USB-TTL adapter as shown in the RPC section. + +- Open the USB-TTL serial port and type `help` to view the available commands + +- To know what are the available subcommands are there, enter `switch` command + in the shell + +## Binding and Controlling a Device + +- This example shows how to bind a Switch Device to a Controllee Device and + control it through the Matter Shell. One binding client (Switch Device) and + one binding server (Controllee) is required. + +- Commission the switch (nodeID 1) and controllee device (nodeID 2) using + chip-tool. + + $ ./chip-tool pairing ble-wifi 1 20202021 3840 + $ ./chip-tool pairing ble-wifi 2 20202021 3840 + +- After successful commissioning, configure the ACL in the controllee device + to allow access from switch device and chip-tool. + + $ ./chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null },{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [1], "targets": null }]' 2 0 + +- Bind the endpoint 1 OnOff cluster of the controllee device to the switch + device. + + $ ./chip-tool binding write binding '[{"fabricIndex": 1, "node":2, "endpoint":1, "cluster":6}]' 1 1 + +- Send OnOff command to the device through the switch device's Matter Shell + + `switch onoff on` + + `switch onoff off` + +* You may also bind more than one cluster to the switch device. Below command + binds the Identify, OnOff, LevelControl, ColorControl and Thermostat + clusters to the switch device. + + $ ./chip-tool binding write binding '[{"fabricIndex": 1, "node":2, "endpoint":1, "cluster":3}, {"fabricIndex": 1, "node":2, "endpoint":1, "cluster":6}, {"fabricIndex": 1, "node":2, "endpoint":1, "cluster":8}, {"fabricIndex": 1, "node":2, "endpoint":1, "cluster":768}, {"fabricIndex": 1, "node":2, "endpoint":1, "cluster":513}]' 1 1 + +- After binding the clusters, you may send these cluster commands to the + controllee device through the switch device's Matter Shell. Follow the + format shown in the description of the commands. + + `switch onoff on` + + `switch levelcontrol movetolevel 100 0 0 0` + + `switch colorcontrol movetohue 100 0 0 0 0` + + `switch thermostat SPRL 0 0` + +* You may also request to read cluster attributes from Matter Shell + + `switch read ` diff --git a/_sources/examples/all-clusters-app/asr/README.md b/_sources/examples/all-clusters-app/asr/README.md new file mode 100644 index 000000000000..9f8821f22fe3 --- /dev/null +++ b/_sources/examples/all-clusters-app/asr/README.md @@ -0,0 +1,54 @@ +# Matter ASR All Clusters Example + +A prototype application that demonstrates device commissioning and cluster +control on ASR platform. + +--- + +- [Matter ASR All Clusters Example](#matter-asr-all-clusters-example) + - [Building and Commissioning](#building-and-commissioning) + - [Cluster Control](#cluster-control) + - [Light switch press button and light status LED](#light-switch-press-button-and-light-status-led) + +--- + +## Building and Commissioning + +Please refer +[Building and Commissioning](../../../guides/asr_getting_started_guide.md#building-the-example-application) +guides to get started + +``` +./scripts/build/build_examples.py --target asr-$ASR_BOARD-all-clusters build +``` + +## Cluster Control + +After successful commissioning, use `chip-tool` to control the board + +For example, read sensor measured value: + +``` +./chip-tool temperaturemeasurement read measured-value 1 +./chip-tool relativehumiditymeasurement read measured-value 1 +./chip-tool pressuremeasurement read measured-value 1 +``` + +Or,control the OnOff Cluster attribute: + +``` +./chip-tool onoff read on-off 1 +./chip-tool onoff on 1 +./chip-tool onoff off 1 +./chip-tool onoff toggle 1 +``` + +## Light switch press button and light status LED + +This demo uses button to test changing the light states and LED to show the +state of these changes. + +| Name | Pin | +| :----: | :---: | +| LED | PAD6 | +| BUTTON | PAD12 | diff --git a/_sources/examples/all-clusters-app/cc13x4_26x4/README.md b/_sources/examples/all-clusters-app/cc13x4_26x4/README.md new file mode 100644 index 000000000000..ef0fdaf1b413 --- /dev/null +++ b/_sources/examples/all-clusters-app/cc13x4_26x4/README.md @@ -0,0 +1,304 @@ +# Matter All-clusters Example Application + +An example application showing the use of [Matter][matter] on the Texas +Instruments CC13XX_26XX family of Wireless MCUs. + +--- + +- [Matter All Clusters Example Application](#matter-all-clusters-example-application) + - [Introduction](#introduction) + - [Device UI](#device-ui) + - [Building](#building) + - [Preparation](#preparation) + - [Compilation](#compilation) + - [Programming](#programming) + - [Code Composer Studio](#code-composer-studio) + - [UniFlash](#uniflash) + - [Running the Example](#running-the-example) + - [Provisioning](#provisioning) + - [Bluetooth LE Advertising](#bluetooth-le-advertising) + - [Bluetooth LE Rendezvous](#bluetooth-le-rendezvous) + - [TI Support](#ti-support) + +--- + +## Introduction + +The CC13XX_26XX all clusters example application provides the basis to query and +run commands for all currently implemented Matter clusters. This uses the +open-source Matter implementation and the Texas Instruments SimpleLink™ CC13XX +and CC26XX software development kit. + +This example is enabled to build for CC1354P10 devices. + +The all-clusters example is intended to serve both as a means to explore the +workings of Matter, as well as a template for creating real products based on +the Texas Instruments devices. + +## Device UI + +| Action | Functionality | +| ------------------------------------------------ | --------------------------------------------- | +| Left Button (`BTN-1`) Press (more than 1000 ms) | Factory Reset | +| Right Button (`BTN-2`) Press (more than 1000 ms) | BLE Advertisement (Enable/Disable) | +| Red LED Solid Blinking State | Identify Trigger Effect in progress (`EP0/1`) | +| Red LED Off State | No Identify Trigger Effect in progress | +| Green LED Blinking State | Identify Trigger Effect in progress (`EP2`) | +| Green LED Off State | No Identify Trigger Effect in progress | + +## Building + +### Preparation + +Some initial setup is necessary for preparing the build environment. This +section will need to be done when migrating to new versions of the SDK. This +guide assumes that the environment is linux based, and recommends Ubuntu 20.04. + +- Download and install [SysConfig][sysconfig]. This can be done simply with + the following commands. + + ``` + $ cd ~ + $ wget https://dr-download.ti.com/software-development/ide-configuration-compiler-or-debugger/MD-nsUM6f7Vvb/1.18.1.3343/sysconfig-1.18.1_3343-setup.run + $ chmod +x sysconfig-1.18.1_3343-setup.run + $ ./sysconfig-1.18.1_3343-setup.run + ``` + +- Run the bootstrap script to setup the build environment. + + ``` + $ cd ~/connectedhomeip + $ source ./scripts/bootstrap.sh + + ``` + +### Compilation + +It is necessary to activate the environment in every new shell. Then run GN and +Ninja to build the executable. + +- Activate the build environment with the repository activate script. + + ``` + $ cd ~/connectedhomeip + $ source ./scripts/activate.sh + + ``` + +- Run the build to produce a default executable. By default on Linux both the + TI SimpleLink SDK and Sysconfig are located in a `ti` folder in the user's + home directory, and you must provide the absolute path to them. For example + `/home/username/ti/sysconfig_1.18.1`. On Windows the default directory is + `C:\ti`. Take note of this install path, as it will be used in the next + step. + + ``` + $ cd ~/connectedhomeip/examples/all-clusters-minimal-app/cc13x4_26x4 + $ gn gen out/debug --args="ti_sysconfig_root=\"$HOME/ti/sysconfig_1.18.1\"" + $ ninja -C out/debug + + ``` + + If you would like to define arguments on the command line you may add them + to the GN call. + + ``` + gn gen out/debug --args="ti_sysconfig_root=\"$HOME/ti/sysconfig_1.18.1\" target_defines=[\"CC13X4_26X4_ATTESTATION_CREDENTIALS=1\"]" + ``` + +## Programming + +Loading the built image onto a LaunchPad is supported through two methods; +Uniflash and Code Composer Studio (CCS). UniFlash can be used to load the image. +Code Composer Studio can be used to load the image and debug the source code. + +### Code Composer Studio + +Programming with CCS will allow for a full debug environment within the IDE. +This is accomplished by creating a target connection to the XDS110 debugger and +starting a project-less debug session. The CCS IDE will attempt to find the +source files on the local machine based on the debug information embedded within +the ELF. CCS may prompt you to find the source code if the image was built on +another machine or the source code is located in a different location than is +recorded within the ELF. + +Download and install [Code Composer Studio][ccs]. + +First open CCS and create a new workspace. + +Create a target connection (sometimes called the CCXML) for your target SoC and +debugger as described in the [Manual Method][ccs_manual_method] section of the +CCS User's Guide. + +Next initiate a project-less debug session as described in the [Manual +Launch][ccs_manual_launch] section of the CCS User's Guide. + +CCS should switch to the debug view described in the [After +Launch][ccs_after_launch] section of the User's Guide. The SoC core will likely +be disconnected and symbols will not be loaded. Connect to the core as described +in the [Debug View][ccs_debug_view] section of the User's Guide. Once the core +is connected, use the `Load` button on the toolbar to load the ELF image. + +Note that the default configuration of the CCXML uses 2-wire cJTAG instead of +the full 4-wire JTAG connection to match the default jumper configuration of the +LaunchPad. + +### UniFlash + +Uniflash is Texas Instrument's uniform programming tool for embedded processors. +This will allow you to erase, flash, and inspect the SoC without setting up a +debugging environment. + +Download and install [UniFlash][uniflash]. + +First open UniFlash. Debug probes connected to the computer will usually be +displayed under the Detected Devices due to the automatic device detection +feature. If your device does not show up in this view it my be disconnected, or +you may have to create a New Configuration. If you already have a CCXML for your +SoC and debug connection you can use that in the section at the bottom. Once +your device is selected, click the `Start` button within the section to launch +the session. + +Select the ELF image to load on the device with the `Browse` button. This file +is placed in the `out/debug` folder by this guide and ends with the `*.out` file +extension. For OTA enabled applications, the standalone image will instead end +with the `*-mcuboot.hex` file extension. This this is a combined image with +application and `MCUBoot` included. The flag to enable or disable the OTA +feature is determined by "chip_enable_ota_requestor" in the application's +args.gni file. + +Finally click the `Load Image` button to load the executable image onto the +device. You should be able to see the log output over the XDS110 User UART. + +Note that programming the device through JTAG sets the Halt-in-Boot flag and may +cause issues when performing a software reset. This flag can be reset by +power-cycling the LaunchPad. + +## Running the Example + +By default the log output will be sent to the Application/User UART. Open a +terminal emulator to that port to see the output with the following options: + +| Parameter | Value | +| ------------ | -------- | +| Speed (baud) | `115200` | +| Data bits | `8` | +| Stop bits | `1` | +| Parity | `None` | +| Flow control | `None` | + +## Running the Example + +Once a device has been flashed with this example, it can now join and operate in +an existing Matter network. The following sections assume that a Matter network +is already active, and has at least one [OpenThread Border +Router][ot_border_router_setup]. + +For insight into what other components are needed to run this example, please +refer to our [Matter Getting Started Guide][matter-e2e-faq]. + +The steps below should be followed to commission the device onto the network and +control it once it has been commissioned. + +**Step 0** + +Set up the CHIP tool by following the instructions outlined in our [Matter +Getting Started Guide][matter-e2e-faq]. + +**Step 1** + +Commission the device onto the Matter network. Run the following command on the +CHIP tool: + +``` + +./chip-tool pairing ble-thread hex: 20202021 3840 + +``` + +Interacting with the application begins by enabling BLE advertisements and then +pairing the device into a Thread network. To provision this example onto a +Matter network, the device must be discoverable over Bluetooth LE. + +On the LaunchPad, press and hold the right button, labeled `BTN-2`, for more +than 1 second. Upon release, the Bluetooth LE advertising will begin. Once the +device is fully provisioned, BLE advertising will stop. + +Once the device has been successfully commissioned, you will see the following +message on the CHIP tool output: + +``` + +[1677648218.370754][39785:39790] CHIP:CTL: Received CommissioningComplete response, errorCode=0 +[1677648218.370821][39785:39790] CHIP:CTL: Successfully finished commissioning step 'SendComplete' + +``` + +An accompanying message will be seen from the device: + +``` + +Commissioning complete, notify platform driver to persist network credentials. + +``` + +**Step 2** + +Send commands to the all-cluster-app. Here are some example commands: + +Basic + +``` +./chip-tool basic read e.g. ./chip-tool basic read product-id 1 0 +``` + +Identify + +``` +./chip-tool identify identify e.g. ./chip-tool identify identify 100 1 1 +``` + +### Provisioning + +Interacting with the application begins by enabling BLE advertisements and then +pairing the device into a Thread network. + +#### Bluetooth LE Advertising + +To provision this example onto a Thread network, the device must be discoverable +over Bluetooth LE. BLE advertising is started by long pressing the right button +(greater than 1000ms), labeled `BTN-2` on the silkscreen. Once the device is +fully provisioned, BLE advertising will stop. + +#### Bluetooth LE Rendezvous + +Pairing this application with `ble-thread` can be done with any of the enabled +[CHIP Controller](https://github.com/project-chip/connectedhomeip/blob/master/src/controller/README.md) applications. Use the +information printed on the console to aide in pairing the device. The controller +application can also be used to control the example app with the cluster +commands. + +## TI Support + +For technical support, please consider creating a post on TI's [E2E forum][e2e]. +Additionally, we welcome any feedback. + +[matter]: https://csa-iot.org/all-solutions/matter/ +[ccs]: https://www.ti.com/tool/CCSTUDIO +[ccs_after_launch]: + https://software-dl.ti.com/ccs/esd/documents/users_guide/ccs_debug-main.html?configuration#after-launch +[ccs_debug_view]: + https://software-dl.ti.com/ccs/esd/documents/users_guide/ccs_debug-main.html?configuration#debug-view +[ccs_manual_launch]: + https://software-dl.ti.com/ccs/esd/documents/users_guide/ccs_debug-main.html?configuration#manual-launch +[ccs_manual_method]: + https://software-dl.ti.com/ccs/esd/documents/users_guide/ccs_debug-main.html?configuration#manual-method +[e2e]: + https://e2e.ti.com/support/wireless-connectivity/zigbee-thread-group/zigbee-and-thread/f/zigbee-thread-forum +[matter-e2e-faq]: + https://e2e.ti.com/support/wireless-connectivity/zigbee-thread-group/zigbee-and-thread/f/zigbee-thread-forum/1082428/faq-cc2652r7-matter----getting-started-guide +[sysconfig]: https://www.ti.com/tool/SYSCONFIG +[ti_thread_dnd]: + https://www.ti.com/wireless-connectivity/thread/design-development.html +[ot_border_router_setup]: https://openthread.io/guides/border-router/build +[uniflash]: https://www.ti.com/tool/download/UNIFLASH diff --git a/_sources/examples/all-clusters-app/esp32/README.md b/_sources/examples/all-clusters-app/esp32/README.md new file mode 100644 index 000000000000..c3159d6c7569 --- /dev/null +++ b/_sources/examples/all-clusters-app/esp32/README.md @@ -0,0 +1,70 @@ +# Matter ESP32 All Clusters Example + +A prototype application that demonstrates device commissioning and cluster +control. + +Please +[setup ESP-IDF and CHIP Environment](../../../guides/esp32/setup_idf_chip.md) +and refer +[building and commissioning](../../../guides/esp32/build_app_and_commission.md) +guides to get started. + +--- + +- [Cluster control](#cluster-control) +- [Matter OTA guide](../../../guides/esp32/ota.md) +- [RPC console and Device Tracing](../../../guides/esp32/rpc_console.md) +- [Multiple Network Interfaces](#multiple-network-interfaces) + +--- + +### Cluster control + +#### onoff + +To use the Client to send Matter commands, run the built executable and pass it +the target cluster name, the target command name as well as an endpoint id. + +``` +$ ./out/debug/chip-tool onoff on +``` + +The client will send a single command packet and then exit. + +#### levelcontrol + +```bash +Usage: + $ ./out/debug/chip-tool levelcontrol move-to-level Level=10 TransitionTime=0 OptionMask=0 OptionOverride=0 +``` + +### Multiple Network Interfaces + +The data model of this example includes a secondary NetworkCommissioning +Endpoint with another NetworkCommissioning cluster. The Endpoint Id for the +secondary NetworkCommissioning Endpoint is 65534. The secondary +NetworkCommissioning Endpoint can be used to manage the driver of extra network +interface. + +For ESP32-C6 DevKits, if `CHIP_DEVICE_CONFIG_ENABLE_WIFI` and +`CHIP_DEVICE_CONFIG_ENABLE_THREAD` are both enabled, the NetworkCommissioning +cluster in Endpoint 0 will be used for Thread network driver and the same +cluster on Endpoint 65534 will be used for Wi-Fi network driver. + +For ESP32-Ethernet-Kits, if `CHIP_DEVICE_CONFIG_ENABLE_WIFI` and +`CHIP_DEVICE_CONFIG_ENABLE_ETHERNET` are both enabled, the NetworkCommissioning +cluster in Endpoint 0 will be used for Ethernet network driver and the same +cluster on Endpoint 65534 will be used for Wi-Fi network driver. + +--- + +This demo app illustrates controlling OnOff cluster (Server) attributes of an +endpoint. For `ESP32-DevKitC`, `ESP32-WROVER-KIT_V4.1` and `ESP32C3-DevKitM`, a +GPIO (configurable through `STATUS_LED_GPIO_NUM` in `main/main.cpp`) is updated +through the on/off/toggle commands from the `python-controller`. For `M5Stack`, +a virtual Green LED on the display is used for the same. + +If you wish to see the actual effect of the commands on `ESP32-DevKitC`, +`ESP32-WROVER-KIT_V4.1`, you will have to connect an external LED to GPIO +`STATUS_LED_GPIO_NUM`. For `ESP32C3-DevKitM`, the on-board LED will show the +actual effect of the commands. diff --git a/_sources/examples/all-clusters-app/infineon/psoc6/README.md b/_sources/examples/all-clusters-app/infineon/psoc6/README.md new file mode 100644 index 000000000000..104be3fadec6 --- /dev/null +++ b/_sources/examples/all-clusters-app/infineon/psoc6/README.md @@ -0,0 +1,127 @@ +# CHIP PSoC6 All Clusters Example + +An example showing the use of Matter on the Infineon CY8CKIT-062S2-43012 board. + +
    + +- [Matter PSoC6 All Clusters Example](#chip-psoc6-all-clusters-example) + - [Introduction](#introduction) + - [Building](#building) + - [Flashing the Application](#flashing-the-application) + - [Commissioning and cluster control](#commissioning-and-cluster-control) + - [Setting up chip-tool](#setting-up-chip-tool) + - [Commissioning over BLE](#commissioning-over-ble) + - [Notes](#notes) + - [Factory Reset](#factory-reset) + - [OTA Software Update](#ota-software-update) + +
    + +## Introduction + +The PSoC6 clusters example provides a baseline demonstration of a Cluster +control device, built using Matter and the Infineon Modustoolbox SDK. It can be +controlled by Matter controller over Wi-Fi network. + +The PSoC6 device can be commissioned over Bluetooth Low Energy where the device +and the Matter controller will exchange security information with the Rendezvous +procedure. Wi-Fi Network credentials are then provided to the PSoC6 device which +will then join the network. + +## Building + +- [Modustoolbox Software](https://www.cypress.com/products/modustoolbox) + + Refer to `integrations/docker/images/chip-build-infineon/Dockerfile` or + `scripts/examples/gn_psoc6_example.sh` for downloading the Software and + related tools. + +- Install some additional tools (likely already present for Matter + developers): + + ``` + sudo apt install gcc g++ clang ninja-build python \ + python3-venv libssl-dev libavahi-client-dev libglib2.0-dev git cmake \ + python3-pip + ``` + +- Supported hardware: + [CY8CKIT-062S2-43012](https://www.cypress.com/CY8CKIT-062S2-43012) + +* Build the example application: + + $ source scripts/activate.sh + $ scripts/build/build_examples.py --no-log-timestamps --target 'infineon-psoc6-all-clusters' build + +- To delete generated executable, libraries and object files use: + + $ cd ~/connectedhomeip + $ rm -rf out/ + +## Flashing the Application + +- Put CY8CKIT-062S2-43012 board on KitProg3 CMSIS-DAP Mode by pressing the + `MODE SELECT` button. `KITPROG3 STATUS` LED is ON confirms board is in + proper mode. + +- On the command line: + + $ cd ~/connectedhomeip + $ python3 out/infineon-psoc6-all-clusters/chip-psoc6-clusters-example.flash.py + +## Commissioning and cluster control + +Commissioning can be carried out using BLE. + +### Setting up Chip tool + +Once PSoC6 is up and running, we need to set up chip-tool on Raspberry Pi 4 to +perform commissioning and cluster control. + +- Set up python controller. + + $ cd {path-to-connectedhomeip} + $ ./scripts/examples/gn_build_example.sh examples/chip-tool out/debug + +- Execute the controller. + + $ ./out/debug/chip-tool + +### Commissioning over BLE + +Run the built executable and pass it the discriminator and pairing code of the +remote device, as well as the network credentials to use. + + $ ./out/debug/chip-tool pairing ble-wifi 1234 ${SSID} ${PASSWORD} 20202021 3840 + + Parameters: + 1. Discriminator: 3840 + 2. Setup-pin-code: 20202021 + 3. Node ID: 1234 (you can assign any node id) + 4. SSID : Wi-Fi SSID + 5. PASSWORD : Wi-Fi Password + +#### Notes + +Raspberry Pi 4 BLE connection issues can be avoided by running the following +commands. These power cycle the BlueTooth hardware and disable BR/EDR mode. + + $ sudo btmgmt -i hci0 power off + $ sudo btmgmt -i hci0 bredr off + $ sudo btmgmt -i hci0 power on + +### Factory Reset + +- Commissioned Wi-Fi Credentials can be cleared by pressing `USER_BTN2` button + on the board. All the data configured on the device during the initial + commissioning will be deleted and device will be ready for commissioning + again. + +- Pressing the button again within 5 seconds will cancel the factory reset of + the board. + +## OTA Software Update + +For the description of Software Update process with infineon PSoC6 example +applications see +[Infineon PSoC6 OTA Software Update](../../../../guides/infineon_psoc6_software_update.md) diff --git a/_sources/examples/all-clusters-app/linux/README.md b/_sources/examples/all-clusters-app/linux/README.md new file mode 100644 index 000000000000..a84fd7577036 --- /dev/null +++ b/_sources/examples/all-clusters-app/linux/README.md @@ -0,0 +1,220 @@ +# Matter Linux/Mac All Clusters Example + +## Compiling all-clusters-app for testing on Linux and Mac + +To compile all-clusters-app on Intel Mac, using the bootstrap-provided clang, +run: + +``` +$ ./scripts/run_in_build_env.sh "./scripts/build/build_examples.py --target darwin-x64-all-clusters-no-ble-asan-clang build" +``` + +at the top level of the Matter tree. + +To compile all-clusters-app on Intel Mac, using the system clang, run: + +``` +$ ./scripts/run_in_build_env.sh "./scripts/build/build_examples.py --target darwin-x64-all-clusters-no-ble-asan build" +``` + +To compile on an Arm Mac, which can only be done using the system clang, run: + +``` +$ ./scripts/run_in_build_env.sh "./scripts/build/build_examples.py --target darwin-arm64-all-clusters-no-ble-asan build" +``` + +Similarly, to compile on Linux x86-64 run: + +``` +$ ./scripts/run_in_build_env.sh "./scripts/build/build_examples.py --target linux-x64-all-clusters-no-ble-asan-clang build" +``` + +And to compile on Linux ARM run: + +``` +$ ./scripts/run_in_build_env.sh "./scripts/build/build_examples.py --target linux-arm64-all-clusters-no-ble-asan-clang build" +``` + +## Fuzzing integration + +This example also supports compilation with libfuzzer enabled. This should be +used when trying to fuzz-test the Matter SDK. + +### Compiling with fuzzing enabled + +To compile with libfuzzer enabled on Mac, run: + +``` +$ ./scripts/run_in_build_env.sh "./scripts/build/build_examples.py --target darwin-x64-all-clusters-no-ble-asan-libfuzzer-clang build" +``` + +at the top level of the Matter tree. + +Similarly, to compile on Linux run: + +``` +$ ./scripts/run_in_build_env.sh "./scripts/build/build_examples.py --target linux-x64-all-clusters-no-ble-asan-libfuzzer-clang build" +``` + +### Running libfuzzer-enabled binaries + +#### Initial run + +To run the resulting binary with no particular inputs do: + +``` +$ ./out/darwin-x64-all-clusters-no-ble-asan-libfuzzer-clang/chip-all-clusters-app-fuzzing +``` + +or + +``` +$ ./out/linux-x64-all-clusters-no-ble-asan-libfuzzer-clang/chip-all-clusters-app-fuzzing +``` + +If this crashes, it will output the input that caused the crash in a variety of +formats, looking something like this: + +``` +0xe,0x0,0xf1,0xb1,0xf1,0xf1,0xf1,0xf1,0xed,0x73,0x7,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0xc1,0x0,0x0,0x0,0x0,0x0,0x5c,0xf3,0x25,0x0,0x0,0x0,0x0,0x0, +\016\000\361\261\361\361\361\361\355s\007\000\000\000\000\000\000\000\301\000\000\000\000\000\\\363%\000\000\000\000\000 +artifact_prefix='./'; Test unit written to ./crash-c9fd2434ccf4a33a7f49765dcc519e1fd529a8e5 +Base64: DgDxsfHx8fHtcwcAAAAAAAAAwQAAAAAAXPMlAAAAAAA= +``` + +Note that this creates a file holding the input that caused the crash. + +#### Run with a fixed input + +To run the binary with a specific input, place the input bytes in a file (which +a crashing run of the fuzzer does automatically). If `$(INPUT_FILE)` is the name +of that file, then run: + +``` +$ ./out/darwin-x64-all-clusters-no-ble-asan-libfuzzer-clang/chip-all-clusters-app-fuzzing $(INPUT_FILE) +``` + +or + +``` +$ ./out/linux-x64-all-clusters-no-ble-asan-libfuzzer-clang/chip-all-clusters-app-fuzzing $(INPUT_FILE) +``` + +#### Additional execution options. + +The binary can be run with `-help=1` to see more available options. + +Running with `ASAN_OPTIONS="handle_abort=2"` set in the environment may produce +nicer stack traces. + +### Trigger event using all-cluster-app event named pipe + +You can send a command to all-cluster-app to trigger specific event via +all-cluster-app event named pipe /tmp/chip_all_clusters_fifo-. + +#### Trigger `SoftwareFault` events + +1. Generate event `SoftwareFault` when a software fault takes place on the Node. + +``` +$ echo '{"Name":"SoftwareFault"}' > /tmp/chip_all_clusters_fifo- +``` + +#### Trigger `HardwareFault` events + +1. Generate event `HardwareFaultChange` to indicate a change in the set of + hardware faults currently detected by the Node. + +``` +$ echo '{"Name":"HardwareFaultChange"}' > /tmp/chip_all_clusters_fifo- +``` + +2. Generate event `RadioFaultChange` to indicate a change in the set of radio + faults currently detected by the Node. + +``` +$ echo '{"Name":"RadioFaultChange"}' > /tmp/chip_all_clusters_fifo- +``` + +3. Generate event `NetworkFaultChange` to indicate a change in the set of + network faults currently detected by the Node. + +``` +$ echo '{"Name":"NetworkFaultChange"}' > /tmp/chip_all_clusters_fifo- +``` + +4. Generate event `BootReason` to indicate the reason that caused the device to + start-up, from the following set of `BootReasons`. + +- `PowerOnReboot` The Node has booted as the result of physical interaction + with the device resulting in a reboot. + +- `BrownOutReset` The Node has rebooted as the result of a brown-out of the + Node’s power supply. + +- `SoftwareWatchdogReset` The Node has rebooted as the result of a software + watchdog timer. + +- `HardwareWatchdogReset` The Node has rebooted as the result of a hardware + watchdog timer. + +- `SoftwareUpdateCompleted` The Node has rebooted as the result of a completed + software update. + +- `SoftwareReset` The Node has rebooted as the result of a software initiated + reboot. + +``` +$ echo '{"Name":""}' > /tmp/chip_all_clusters_fifo- +``` + +#### Trigger Switch events + +1. Generate event `SwitchLatched`, when the latching switch is moved to a new + position. + +``` +$ echo '{"Name":"SwitchLatched","NewPosition":3}' > /tmp/chip_all_clusters_fifo- +``` + +2. Generate event `InitialPress`, when the momentary switch starts to be + pressed. + +``` +$ echo '{"Name":"InitialPress","NewPosition":3}' > /tmp/chip_all_clusters_fifo- +``` + +3. Generate event `LongPress`, when the momentary switch has been pressed for a + "long" time. + +``` +$ echo '{"Name":"LongPress","NewPosition":3}' > /tmp/chip_all_clusters_fifo- +``` + +4. Generate event `ShortRelease`, when the momentary switch has been released. + +``` +$ echo '{"Name":"ShortRelease","PreviousPosition":3}' > /tmp/chip_all_clusters_fifo- +``` + +5. Generate event `LongRelease` when the momentary switch has been released and + after having been pressed for a long time. + +``` +$ echo '{"Name":"LongRelease","PreviousPosition":3}' > /tmp/chip_all_clusters_fifo- +``` + +6. Generate event `MultiPressOngoing` to indicate how many times the momentary + switch has been pressed in a multi-press sequence, during that sequence. + +``` +$ echo '{"Name":"MultiPressOngoing","NewPosition":3,"CurrentNumberOfPressesCounted":4}' > /tmp/chip_all_clusters_fifo- +``` + +7. Generate event `MultiPressComplete` to indicate how many times the momentary + switch has been pressed in a multi-press sequence, after it has been detected + that the sequence has ended. + +``` +$ echo '{"Name":"MultiPressComplete","PreviousPosition":3,"TotalNumberOfPressesCounted":2}' > /tmp/chip_all_clusters_fifo- +``` diff --git a/_sources/examples/all-clusters-app/mbed/README.md b/_sources/examples/all-clusters-app/mbed/README.md new file mode 100644 index 000000000000..c9cf657a439c --- /dev/null +++ b/_sources/examples/all-clusters-app/mbed/README.md @@ -0,0 +1,276 @@ +![ARM Mbed-OS logo](https://raw.githubusercontent.com/ARMmbed/mbed-os/master/logo.png) + +# Matter Arm Mbed OS All Clusters Example Application + +The Arm Mbed OS All Clusters Example demonstrates device commissioning process +and all available clusters control. + +You can use this example as a reference for creating your own application. + +The example is based on +[Matter](https://github.com/project-chip/connectedhomeip) and Arm Mbed OS, and +supports remote access and control of device over a WiFi network. + +The example behaves as a Matter accessory, in other words a device that can be +paired into an existing Matter network and can be controlled by this network. + +
    + +- [Overview](#overview) + - [Bluetooth Low Energy advertising](#bluetooth-low-energy-advertising) + - [Bluetooth Low Energy rendezvous](#bluetooth-low-energy-rendezvous) + - [WiFi provisioning](#wifi-provisioning) +- [Run application](#run-application) + - [Environment setup](#environment-setup) + - [Building](#building) + - [Flashing](#flashing) + - [Debugging](#debugging) + - [Testing](#testing) + - [Serial port terminal](#serial-port-terminal) + - [CHIP Tools](#chip-tools) + - [Supported devices](#supported-devices) + - [Notes](#notes) +- [Device UI](#device-ui) + - [Notes](#notes-1) + +
    + +## Overview + +The Matter device that runs the All Clusters application is controlled by the +Matter controller device over WiFi. By default, the Matter device is +disconnected, and it should be paired with Matter controller and get +configuration from it. Actions required before establishing full communication +are described below. + +### Bluetooth Low Energy advertising + +To commission the device onto a Matter network, the device must be discoverable +over BLE. The BLE advertising starts automatically after device boot-up. + +### Bluetooth Low Energy rendezvous + +In Matter, the commissioning procedure (called rendezvous) is done over BLE +between a Matter device and the Matter controller, where the controller has the +commissioner role. + +To start the rendezvous, the controller must get the commissioning information +from the Matter device. The data payload is encoded within a QR code, printed to +the UART console. + +### WiFi provisioning + +The last part of the rendezvous procedure, provisioning involves sending the +network credentials from the Matter controller to the Matter device. As a +result, device is able to join the network and communicate with other devices in +the network. + +## Run application + +### Environment setup + +Before building the example, check out the Matter repository and sync submodules +using the following command: + + $ git submodule update --init + +Building the example application requires the use of **ARM Mbed-OS** sources and +the **arm-none-gnu-eabi** toolchain. + +The Cypress OpenOCD package is required for flashing purpose. Install the +Cypress OpenOCD and set env var `OPENOCD_PATH` before calling the flashing +script. + +``` +cd ~ +wget https://github.com/Infineon/openocd/releases/download/release-v4.3.0/openocd-4.3.0.1746-linux.tar.gz +tar xzvf openocd-4.3.0.1746-linux.tar.gz +export OPENOCD_PATH=$HOME/openocd +``` + +Some additional packages may be needed, depending on selected build target and +its requirements. + +> **The VSCode devcontainer has these components pre-installed. Using the VSCode +> devcontainer is the recommended way to interact with Arm Mbed-OS port of the +> Matter Project.** +> +> **Please read this [README.md](../../../VSCODE_DEVELOPMENT.md) for more +> information about using VSCode in container.** + +To initialize the development environment, download all registered sub-modules +and activate the environment: + +``` +$ source ./scripts/bootstrap.sh +$ source ./scripts/activate.sh +``` + +If packages are already installed then you just need to activate the development +environment: + +``` +$ source ./scripts/activate.sh +``` + +### Building + +The All Clusters application can be built in the same way as any other Matter +example ported to the mbed-os platform. + +- **by using generic vscode task**: + +``` +Command Palette (F1) => Run Task... => Run Mbed Application => build => all-clusters-app => (board name) => (build profile) => (build type) +``` + +- **by calling explicitly building script:** + +``` +${MATTER_ROOT}/scripts/examples/mbed_example.sh -c=build -a=all-clusters-app -b= -p= -T= +``` + +Both approaches are limited to supported evaluation boards which are listed in +[Supported devices](#supported-devices) paragraph. + +Mbed OS defines three building profiles: _develop, debug_ and _release_. For +more details please visit +[ARM Mbed OS build profiles](https://os.mbed.com/docs/mbed-os/latest/program-setup/build-profiles-and-rules.html). + +There are also three types of built application: _simple, boot_ and _upgrade_: + +- **simple** - standalone application, mainly for developing and testing + purpose (all building profiles are supported) +- **boot** - signed application + bootloader, it supports booting process and + can be use for firmware update (only _release_ building profiles is + supported) +- **update** - signed application, application image can be used for firmware + update (only _release_ building profiles is supported) + +When using the building script, it is possible expand the list of acceptable +targets; this may be useful for rapid testing of a new mbed-targets. + +### Flashing + +The All Clusters application can be flashed in the same way as any other Matter +example ported to mbed-os platform. + +The [Open On-Chip Debugger](http://openocd.org/) is used to upload a binary +image and reset the device. + +- **by using VSCode task**: + +``` +Command Palette (F1) => Run Task... -> Run Mbed Application => flash => all-clusters-app => (board name) => (build profile) +``` + +- **by calling explicitly building script:** + +``` +${MATTER_ROOT}/scripts/examples/mbed_example.sh -c=flash -a=all-clusters-app -b= -p= +``` + +- **by using VSCode launch task**: + +``` +Run and Debug (Ctrl+Shift+D) => Flash Mbed examples => Start Debugging (F5) => (board name) => all-clusters-app => (build profile) +``` + +The last option uses the Open On-Chip Debugger to open and manage the gdb-server +session. Then gdb-client (arm-none-eabi-gdb) upload binary image and reset +device. + +It is possible to connect to an external gdb-server session by using a specific +**'Flash Mbed examples [remote]'** task. + +### Debugging + +Debugging can be performed in the same was as with any other Matter example +ported to mbed-os platform. + +The [Open On-Chip Debugger](http://openocd.org/) is used to to open and manage +the gdb-server session. Then gdb-client (arm-none-eabi-gdb) connect the server +to upload binary image and control debugging. + +``` +Run and Debug (Ctrl+Shift+D) => Debug Mbed examples => Start Debugging (F5) => (board name) => all-clusters-app => (build profile) +``` + +It is possible to connect to an external gdb-server session by using specific +**'Debug Mbed examples [remote]'** task. + +### Testing + +#### Serial port terminal + +The application traces are streaming to serial output. To start communication +open a terminal session and connect to the serial port of the device. You can +use **mbed-tools** for this purpose +([mbed-tools](https://github.com/ARMmbed/mbed-tools)): + + ``` + mbed-tools sterm -p /dev/ttyACM0 -b 115200 -e off + ``` + +After device reset these lines should be visible: + + ``` + [INFO][CHIP]: [-]Mbed all-clusters-app example application start + ... + [INFO][CHIP]: [-]Mbed all-clusters-app example application run + ``` + +The all-clusters-app application launched correctly and you can follow traces in +the terminal. + +#### CHIP Tools + +Read the [MbedCommissioning](../../../guides/mbedos_commissioning.md) to +see how to use different CHIP tools to commission and control the application +within a WiFi network. + +### Supported devices + +| Manufacturer | Hardware platform | Build target | Platform image | Status | Platform components | +| ----------------------------------------------------- | ------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------ | :----: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Cypress
    Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` | ![CY8CPROTO-062-4343W](https://os.mbed.com/media/cache/platforms/p6_wifi-bt_proto.png.250x250_q85.jpg) | ✔ |
    LEDs
    • Board has only one usable LED (LED4) which corresponds to USER LED from UI.
    Buttons
    • Unused
    Slider
    • Unused
    | + +##### Notes + +- More details and guidelines about porting new hardware into the Matter + project with Mbed OS can be found in + [MbedNewTarget](../../../guides/mbedos_add_new_target.md) +- Some useful information about HW platform specific settings can be found in + `all-clusters-app/mbed/mbed_app.json`. Information about this file syntax + and its meaning in mbed-os project can be found here: + [Mbed-Os configuration system](https://os.mbed.com/docs/mbed-os/latest/program-setup/advanced-configuration.html)) + +## Device UI + +This section lists the User Interface elements that you can use to control and +monitor the state of the device. These correspond to PCB components on the +platform image. + +**USER LED** shows the overall state of the device and its connectivity. The +following states are possible: + +- _Short Flash On (50 ms on/950 ms off)_ — The device is in the + unprovisioned (unpaired) state and is waiting for a commissioning + application to connect. + +- _Rapid Even Flashing (100 ms on/100 ms off)_ — The device is in the + unprovisioned state and a commissioning application is connected through + Bluetooth LE. + +- _Short Flash Off (950ms on/50ms off)_ — The device is fully + provisioned, but does not yet have full network or service connectivity. + +- _Solid On_ — The device is fully provisioned and has full network and + service connectivity. + +#### Notes + +Some of the supported boards may not have sufficient number PCB components to +follow above description. In that case please refer to +[Supported devices](#supported-devices) section and check board's 'Platform +components' column f-r additional information about the limitation. diff --git a/_sources/examples/all-clusters-app/nrfconnect/README.md b/_sources/examples/all-clusters-app/nrfconnect/README.md new file mode 100644 index 000000000000..cc32d7b83f86 --- /dev/null +++ b/_sources/examples/all-clusters-app/nrfconnect/README.md @@ -0,0 +1,414 @@ +# Matter nRF Connect All Clusters Example Application + +The nRF All Clusters Example Application implements various ZCL clusters +populated on three endpoints. You can use this example as a reference for +creating your own application. + +![Nordic Smiconductor logo](../../platform/nrfconnect/doc/images/Logo_RGB_H-small.png) +![nRF52840 DK](../../platform/nrfconnect/doc/images/nRF52840-DK-small.png) + +The example is based on +[Matter](https://github.com/project-chip/connectedhomeip) and Nordic +Semiconductor's nRF Connect SDK, and was created to facilitate testing and +certification of a Matter device communicating over a low-power 802.15.4 Thread +network, or Wi-Fi network. + +The example behaves as a Matter accessory, that is a device that can be paired +into an existing Matter network and can be controlled by this network. In the +case of Thread, this device works as a Thread Sleepy End Device. Support for +both Thread and Wi-Fi is mutually exclusive and depends on the hardware +platform, so only one protocol can be supported for a specific device. + +
    + +## Overview + +This example is running on the nRF Connect platform, which is based on Nordic +Semiconductor's +[nRF Connect SDK](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/index.html) +and [Zephyr RTOS](https://zephyrproject.org/). Visit Matter's +[nRF Connect platform overview](../../../guides/nrfconnect_platform_overview.md) +to read more about the platform structure and dependencies. + +By default, the Matter accessory device has IPv6 networking disabled. You must +pair it with the Matter controller over Bluetooth® LE to get the configuration +from the controller to use the device within a Thread or Wi-Fi network. You have +to make the device discoverable manually (for security reasons). See +[Bluetooth LE advertising](#bluetooth-le-advertising) to learn how to do this. +The controller must get the commissioning information from the Matter accessory +device and provision the device into the network. + +You can test this application remotely over the Thread or the Wi-Fi protocol, +which in either case requires more devices, including a Matter controller that +you can configure either on a PC or a mobile device. + +### Bluetooth LE advertising + +In this example, to commission the device onto a Matter network, it must be +discoverable over Bluetooth LE. For security reasons, you must start Bluetooth +LE advertising manually after powering up the device by pressing: + +- On nRF52840 DK, nRF5340 DK, and nRF21540 DK: **Button 4**. + +- On nRF7002 DK: **Button 2**. + +### Bluetooth LE rendezvous + +In this example, the commissioning procedure is done over Bluetooth LE between a +Matter device and the Matter controller, where the controller has the +commissioner role. + +To start the rendezvous, the controller must get the commissioning information +from the Matter device. The data payload is encoded within a QR code, printed to +the UART console, and shared using an NFC tag. The emulation of the NFC tag +starts automatically when Bluetooth LE advertising is started and stays enabled +until Bluetooth LE advertising timeout expires. + +#### Thread or Wi-Fi provisioning + +Last part of the rendezvous procedure, the provisioning operation involves +sending the Thread or Wi-Fi network credentials from the Matter controller to +the Matter device. As a result, the device joins the Thread or Wi-Fi network and +can communicate with other devices in the network. + +
    + +## Requirements + +The application requires a specific revision of the nRF Connect SDK to work +correctly. See [Setting up the environment](#setting-up-the-environment) for +more information. + +### Supported devices + +The example supports building and running on the following devices: + +| Hardware platform | Build target | Platform image | +| ------------------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [nRF52840 DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK) | `nrf52840dk_nrf52840` |
    nRF52840 DKnRF52840 DK
    | +| [nRF5340 DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF5340-DK) | `nrf5340dk_nrf5340_cpuapp` |
    nRF5340 DKnRF5340 DK
    | +| [nRF52840 Dongle](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-Dongle) | `nrf52840dongle_nrf52840` |
    nRF52840 DonglenRF52840 Dongle
    | +| [nRF7002 DK](https://www.nordicsemi.com/Products/Development-hardware/nRF7002-DK) | `nrf7002dk_nrf5340_cpuapp` |
    nRF7002 DKnRF7002 DK
    | + +
    + +### IPv6 network support + +The development kits for this sample offer the following IPv6 network support +for Matter: + +- Matter over Thread is supported for `nrf52840dk_nrf52840` and + `nrf5340dk_nrf5340_cpuapp`. +- Matter over Wi-Fi is supported for `nrf7002dk_nrf5340_cpuapp`. + +## Device UI + +This section lists the User Interface elements that you can use to control and +monitor the state of the device. These correspond to PCB components on the +platform image. + +> **Note**: +> +> The following Device UI elements are missing on the nRF52840 Dongle: **Button +> 2**, **Button 3**, **Button 4**, **SEGGER J-Link USB port**, and **NFC port +> with antenna attached**. You can collect logs from the nRF52840 Dongle using +> the **nRF USB port** instead of the **SEGGER J-Link USB port**. +> Functionalities associated with the remaining missing elements are +> inaccessible. + +**LED 1** shows the overall state of the device and its connectivity. The +following states are possible: + +- _Short Flash On (50 ms on/950 ms off)_ — The device is in the + unprovisioned (unpaired) state and is waiting for a commissioning + application to connect. + +- _Rapid Even Flashing (100 ms on/100 ms off)_ — The device is in the + unprovisioned state and a commissioning application is connected through + Bluetooth LE. + +- _Short Flash Off (950ms on/50ms off)_ — The device is fully + provisioned, but does not yet have full connectivity for Thread or Wi-Fi + network. + +- _Solid On_ — The device is fully provisioned. + +**Button 1** can be used for the following purposes: + +- _Pressed for less than 3 s_ — Initiates the OTA software update + process. This feature is disabled by default, but can be enabled by + following the + [Building with Device Firmware Upgrade support](#building-with-device-firmware-upgrade-support) + instructions. + +- _Pressed for more than 3 s_ — initiates the factory reset of the + device. Releasing the button within the 3-second window cancels the factory + reset procedure. + +**Button 2**: + +- On nRF52840 DK, nRF5340 DK, and nRF21540 DK: Not available. + +- On nRF7002 DK: + + - If pressed for more than three seconds, it starts the NFC tag emulation, + enables Bluetooth LE advertising for the predefined period of time (15 + minutes by default), and makes the device discoverable over Bluetooth + LE. + +**Button 4**: + +- On nRF52840 DK, nRF5340 DK, and nRF21540 DK: Starts the NFC tag emulation, + enables Bluetooth LE advertising for the predefined period of time (15 + minutes by default), and makes the device discoverable over Bluetooth LE. + This button is used during the commissioning procedure. + +- On nRF7002 DK: Not available. + +**SEGGER J-Link USB port** can be used to get logs from the device or +communicate with it using the +[command line interface](../../../guides/nrfconnect_examples_cli.md). + +
    + +## Setting up the environment + +Before building the example, check out the Matter repository and sync submodules +using the following command: + + $ python3 scripts/checkout_submodules.py --shallow --platform nrfconnect + +> **Note**: +> +> For Linux operating system install +> [SEGGER J-Link Software](https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack). + +### Install Command Line Tools + +With admin permissions enabled, download and install the +[nRF Command Line Tools](https://www.nordicsemi.com/Products/Development-tools/nrf-command-line-tools). + +### Install Toolchain Manager + +Toolchain Manager is available from +[nRF Connect for Desktop](https://www.nordicsemi.com/Products/Development-tools/nrf-connect-for-desktop), +a cross-platform tool that provides different applications that simplify +installing the nRF Connect SDK. Both the tool and the application are available +for Windows, Linux, and macOS. + +To install the Toolchain Manager app, complete the following steps: + +1. [Download nRF Connect for Desktop](https://www.nordicsemi.com/Products/Development-tools/nrf-connect-for-desktop/download#infotabs) + for your operating system. + +2. Install and run the tool on your machine. + +3. In the **APPS** section, click **Install** button on the Toolchain Manager + tab. + +### Install nRF Connect SDK + +Complete the following steps to install the nRF Connect SDK: + +1. Open Toolchain Manager in nRF Connect for Desktop. + +2. Click the **Install** button next to the + [recommended](https://github.com/project-chip/connectedhomeip/blob/master/config/nrfconnect/.nrfconnect-recommended-revision) + version of the nRF Connect SDK. + +3. A pop-up window will inform you about the current installation directory. If + you want to change the directory, click the **Change directory** button. + Otherwise, click the **Continue installation** button. + +4. When the nRF Connect SDK is installed on your machine, the **Install** + button changes to the **Open VS Code** button. + +5. Click the dropdown menu next to the **Open VS Code** button for the + installed nRF Connect SDK version, and select **Open terminal**. + +6. Make sure that the nRF Connect SDK version is compatible with the Matter SDK + version: + + ``` + $ cd {connectedhomeip directory} + $ python3 scripts/setup/nrfconnect/update_ncs.py --update + ``` + +Now you can proceed with the [Building](#building) instruction. + +
    + +## Building + +Complete the following steps to build the sample: + +1. Navigate to the example's directory: + + $ cd examples/all-clusters-app/nrfconnect + +2. Run the following command to build the example, with _build-target_ replaced + with the build target name of the Nordic Semiconductor's kit you own, for + example `nrf52840dk_nrf52840`: + + $ west build -b build-target + + You only need to specify the build target on the first build. See + [Requirements](#requirements) for the build target names of compatible kits. + +The output `zephyr.hex` file will be available in the `build/zephyr/` directory. + +### Removing build artifacts + +If you're planning to build the example for a different kit or make changes to +the configuration, remove all build artifacts before building. To do so, use the +following command: + + $ rm -r build + +### Building with release configuration + +To build the example with release configuration that disables the diagnostic +features like logs and command-line interface, run the following command: + + $ west build -b build-target -- -DCONF_FILE=prj_release.conf + +Remember to replace _build-target_ with the build target name of the Nordic +Semiconductor's kit you own. + +### Building with Device Firmware Upgrade support + +Support for DFU using Matter OTA is disabled by default. + +To build the example with configuration that supports DFU, run the following +command with _build-target_ replaced with the build target name of the Nordic +Semiconductor kit you are using (for example `nrf52840dk_nrf52840`): + + $ west build -b build-target -- -DCONF_FILE=prj_dfu.conf + +> **Note**: +> +> There are two types of Device Firmware Upgrade modes: single-image DFU and +> multi-image DFU. Single-image mode supports upgrading only one firmware image, +> the application image, and should be used for single-core nRF52840 DK devices. +> Multi-image mode allows to upgrade more firmware images and is suitable for +> upgrading the application core and network core firmware in two-core nRF5340 +> DK devices. +> +> Currently the multi-image mode is not available for the Matter OTA DFU. + +#### Changing bootloader configuration + +To change the default MCUboot configuration, edit the `prj.conf` file located in +the `child_image/mcuboot` directory. + +#### Changing flash memory settings + +In the default configuration, the MCUboot uses the +[Partition Manager](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/scripts/partition_manager/partition_manager.html#partition-manager) +to configure flash partitions used for the bootloader application image slot +purposes. You can change these settings by defining +[static partitions](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/scripts/partition_manager/partition_manager.html#ug-pm-static). +This example uses this option to define using an external flash. + +To modify the flash settings of your board (that is, your _build-target_, for +example `nrf52840dk_nrf52840`), edit the `pm_static_dfu.yml` file located in the +`configuration/build-target/` directory. + +
    + +## Configuring the example + +The Zephyr ecosystem is based on Kconfig files and the settings can be modified +using the menuconfig utility. + +To open the menuconfig utility, run the following command from the example +directory: + + $ west build -b build-target -t menuconfig + +Remember to replace _build-target_ with the build target name of the Nordic +Semiconductor's kit you own. + +Changes done with menuconfig will be lost if the `build` directory is deleted. +To make them persistent, save the configuration options in the `prj.conf` file. + +### Example build types + +The example uses different configuration files depending on the supported +features. Configuration files are provided for different build types and they +are located in the application root directory. + +The `prj.conf` file represents a debug build type. Other build types are covered +by dedicated files with the build type added as a suffix to the prj part, as per +the following list. For example, the release build type file name is +`prj_release.conf`. If a board has other configuration files, for example +associated with partition layout or child image configuration, these follow the +same pattern. + +Before you start testing the application, you can select one of the build types +supported by the sample. This sample supports the following build types, +depending on the selected board: + +- debug -- Debug version of the application - can be used to enable additional + features for verifying the application behavior, such as logs or + command-line shell. +- release -- Release version of the application - can be used to enable only + the necessary application functionalities to optimize its performance. It + has Device Firmware Upgrade feature enabled. It can be used only for the + nRF52840 DK and nRF5340 DK, as only those platforms support the DFU. +- dfu -- Debug version of the application with Device Firmware Upgrade feature + support. It can be used only for the nRF52840 DK and nRF5340 DK, as only + those platforms support the DFU. + +For more information, see the +[Configuring nRF Connect SDK examples](../../../guides/nrfconnect_examples_configuration.md) +page. + +
    + +## Flashing and debugging + +The flashing and debugging procedure is different for the development kits and +the nRF52840 Dongle. + +### Flashing on the development kits + +To flash the application to the device, use the west tool and run the following +command from the example directory: + + $ west flash --erase + +If you have multiple development kits connected, west will prompt you to pick +the correct one. + +To debug the application on target, run the following command from the example +directory: + + $ west debug + +### Flashing on the nRF52840 Dongle + +Visit +[Programming and Debugging nRF52840 Dongle](https://docs.zephyrproject.org/latest/boards/arm/nrf52840dongle_nrf52840/doc/index.html#programming-and-debugging) +to read more about flashing on the nRF52840 Dongle. + +
    + +## Testing the example + +Check the [CLI tutorial](../../../guides/nrfconnect_examples_cli.md) to +learn how to use command-line interface of the application. + +### Testing using Linux CHIPTool + +Read the [CHIP Tool user guide](../../../guides/chip_tool_guide.md) to see +how to use [CHIP Tool for Linux or mac OS](../../chip-tool/README.md) to +commission and control the application within a Matter-enabled Thread network. + +### Testing using Android CHIPTool + +Read the +[Android commissioning guide](../../../guides/nrfconnect_android_commissioning.md) +to see how to use [CHIPTool](https://github.com/project-chip/connectedhomeip/blob/master/examples/android/CHIPTool/README.md) for +Android smartphones to commission and control the application within a +Matter-enabled Thread network. diff --git a/_sources/examples/all-clusters-app/nxp/mw320/README.md b/_sources/examples/all-clusters-app/nxp/mw320/README.md new file mode 100644 index 000000000000..e49d975eb252 --- /dev/null +++ b/_sources/examples/all-clusters-app/nxp/mw320/README.md @@ -0,0 +1,90 @@ +# Matter MW320 All Clusters Example Application + +The example is based on +[Matter](https://github.com/project-chip/connectedhomeip) and the NXP MW320 SDK +to demonstrates device commissioning and cluster control over a low-power, WiFi +802.11n network. + +
    + +- [Matter MW320 All Clusters Example Application](#matter-mw320-all-clusters-example-application) +- [Introduction](#introduction) +- [Building](#building) +- [Flashing](#flashing) + +
    + +## Introduction + +![MW320](../../../platform/nxp/mw320/doc/images/mw320.jpg) + +The example targets the +[NXP MW320 WiFi Micro controller Soc](https://www.nxp.com/products/wireless/wi-fi-plus-bluetooth/88mw32x-802-11n-wi-fi-microcontroller-soc:88MW32X) +development kit. + +## Building + +Building the example application is quite straightforward. It can be done via +following commands: + +``` +$ cd examples/all-clusters-app/nxp/mw320/ +$ git submodule update --init +$ source third_party/connectedhomeip/scripts/activate.sh +$ gn gen out/debug +$ ninja -v -C out/debug +``` + +Example application binary file "chip-mw320-all-clusters-app.bin" will be +generated under directory "out/debug". + +Note: + +1. "git submodule update --init" only needs to be issued for the first time in + order to download MW320 SDK for Matter. +2. "source third_party/connectedhomeip/scripts/activate.sh" can be omitted if + your environment is already setup without issues. + +Tinycrypt ECC operations: + +Note: This solution is temporary. + +In order to use the tinycrypt ecc operations, use the following build arguments: + +``` +$ gn gen out/debug --args='treat_warnings_as_errors=false mbedtls_repo="//third_party/connectedhomeip/third_party/nxp/libs/mbedtls" chip_crypto="tinycrypt"' +``` + +## Flashing + +Connect MW320 to Ubuntu USB port and open Linux text-based serial port +communications program at second USB interface (/dev/ttyUSB1): + +``` +$ TERM=linux minicom -D /dev/ttyUSB1 -b 115200 +``` + +Prepare MW320 download firmware image: + +``` +$ ln -sf third_party/connectedhomeip/third_party/nxp/mw320_sdk/repo mw320_sdk +$ mw320_sdk/tools/mw_img_conv/bin/mw_img_conv mcufw out/debug/chip-mw320-all-clusters-app.bin out/debug/all-cluster-mw320.mcufw.bin 0x1F010000 +$ cp out/debug/all-cluster-mw320.mcufw.bin mw320_sdk/mw320_matter_flash/Matter/. +``` + +Install OpenOCD (Open On-Chip Debugger): + +``` +$ sudo apt-get install openocd +``` + +Flashing firmware image to MW320: + +``` +$ cd mw320_sdk/mw320_matter_flash +$ sudo python2 flashprog.py -l Matter/layout-4m.txt --boot2 Matter/boot2.bin --wififw Matter/mw32x_uapsta_W14.88.36.p172.bin --mcufw Matter/all-cluster-mw320.mcufw.bin -r +``` + +After MW320 is reset, console will allow you to enter commands: + +![MW320_CONSOLE](../../../platform/nxp/mw320/doc/images/mw320_console.jpg) diff --git a/_sources/examples/all-clusters-app/nxp/rt/rw61x/README.md b/_sources/examples/all-clusters-app/nxp/rt/rw61x/README.md new file mode 100644 index 000000000000..e08f617063b2 --- /dev/null +++ b/_sources/examples/all-clusters-app/nxp/rt/rw61x/README.md @@ -0,0 +1,377 @@ +# CHIP RW61x All-clusters Application + +The all-clusters example implements a server which can be accessed by a CHIP +controller and can accept basic cluster commands. + +The example is based on +[Project CHIP](https://github.com/project-chip/connectedhomeip) and the NXP +RW612 SDK, and provides a prototype application that demonstrates device +commissioning and different cluster control. + +
    + +- [Introduction](#introduction) +- [Building](#building) +- [Flashing and debugging](#flashing-and-debugging) +- [Testing the example](#testing-the-example) +- [Matter Shell](#testing-the-all-clusters-application-with-matter-cli-enabled) +- [OTA Software Update](#ota-software-update) + +
    + + + +## Introduction + +The RW61x all-cluster application provides a working demonstration of the +RW610/RW612 board integration, built using the Project CHIP codebase and the NXP +RW612 SDK. + +The example supports: + +- Matter over Wi-Fi +- Matter over Openthread +- Matter over Wi-Fi with OpenThread Border Router support. + +### Hardware requirements + +For Matter over Thread configuration : + +- [`NXP RD-RW612-BGA`] board +- BLE/15.4 antenna (to plug in Ant1) + +For Matter over WiFi configuration : + +- [`NXP RD-RW612-BGA`] or [`NXP RD-RW610-BGA`] board +- BLE antenna (to plug in Ant1) +- Wi-Fi antenna (to plug in Ant2) + +For Matter over Wi-Fi with OpenThread Border Router : + +- [`NXP RD-RW612-BGA`] board +- BLE/15.4 antenna (to plug in Ant1) +- Wi-Fi antenna (to plug in Ant2) + + + +## Building + +In order to build the Project CHIP example, we recommend using a Linux +distribution (the demo-application was compiled on Ubuntu 20.04). + +- Follow instruction in [BUILDING.md](../../../../../guides/BUILDING.md) + to setup the environment to be able to build Matter. + +- Download + [RD-RW612 SDK for Project CHIP](https://mcuxpresso.nxp.com/en/select). + Creating an nxp.com account is required before being able to download the + SDK. Once the account is created, login and follow the steps for downloading + SDK. The SDK Builder UI selection should be similar with the one from the + image below. + + ![MCUXpresso SDK Download](../../../../../../../../examples/platform/nxp/rt/rw61x/doc/images/mcux-sdk-download.PNG) + + (Note: All SDK components should be selected. If size is an issue Azure RTOS + component can be omitted.) + + Please refer to Matter release notes for getting the latest released SDK. + +- Start building the application. + +``` +user@ubuntu:~/Desktop/git/connectedhomeip$ export NXP_SDK_ROOT=/home/user/Desktop/SDK_RW612/ +user@ubuntu:~/Desktop/git/connectedhomeip$ scripts/checkout_submodules.py --shallow --platform nxp --recursive +user@ubuntu:~/Desktop/git/connectedhomeip$ source ./scripts/bootstrap.sh +user@ubuntu:~/Desktop/git/connectedhomeip$ source ./scripts/activate.sh +user@ubuntu:~/Desktop/git/connectedhomeip$ cd examples/all-clusters-app/nxp/rt/rw61x/ +``` + +#### Building with Matter over Wifi configuration on RW61x + +- Build Matter-over-Wifi configuration with BLE commissioning (ble-wifi) : + +``` +user@ubuntu:~/Desktop/git/connectedhomeip/examples/all-clusters-app/nxp/rt/rw61x$ gn gen --args="chip_enable_wifi=true is_sdk_package=true" out/debug +user@ubuntu:~/Desktop/git/connectedhomeip/examples/all-clusters-app/nxp/rt/rw61x$ ninja -C out/debug +``` + +#### Building with Matter over Thread configuration on RW612 + +- Build Matter-over-Thread configuration with BLE commissioning. + +``` +user@ubuntu:~/Desktop/git/connectedhomeip/examples/all-clusters-app/nxp/rt/rw61x$ gn gen --args="chip_enable_openthread=true chip_inet_config_enable_ipv4=false chip_config_network_layer_ble=true is_sdk_package=true" out/debug +user@ubuntu:~/Desktop/git/connectedhomeip/examples/all-clusters-app/nxp/rt/rw61x$ ninja -C out/debug +``` + +#### Building with Matter over Wifi + OpenThread Border Router configuration on RW612 + +This configuration requires enabling the Matter CLI in order to control the +Thread network on the Border Router. + +- Build Matter with Border Router configuration with BLE commissioning + (ble-wifi) : + +``` +user@ubuntu:~/Desktop/git/connectedhomeip/examples/all-clusters-app/nxp/rt/rw610$ gn gen --args="chip_enable_wifi=true chip_enable_openthread=true chip_enable_matter_cli=true is_sdk_package=true openthread_root=\"//third_party/connectedhomeip/third_party/openthread/ot-nxp/openthread-br\"" out/debug +user@ubuntu:~/Desktop/git/connectedhomeip/examples/all-clusters-app/nxp/rt/rw610$ ninja -C out/debug +``` + +#### General information + +The resulting output file can be found in +out/debug/chip-rw61x-all-cluster-example. + +Optional GN options that can be added when building an application: + +- To enable the + [matter CLI](https://github.com/project-chip/connectedhomeip/blob/master/README.md#testing-the-all-clusters-application-with-matter-cli-enabled), + the argument `chip_enable_matter_cli=true` must be added to the _gn gen_ + command. +- To switch the SDK type used, the argument `is_=true` must be added + to the _gn gen_ command (with being either sdk_package or + sdk_internal). +- By default, the RW612 A1 board revision will be chosen. To switch to an A2 + revision, the argument `board_version=\"A2\"` must be added to the _gn gen_ + command. +- To build the application in debug mode, the argument + `is_debug=true optimize_debug=false` must be added to the _gn gen_ command. +- To build with the option to have Matter certificates/keys pre-loaded in a + specific flash area the argument `chip_with_factory_data=1` must be added to + the _gn gen_ command. (for more information see + [Guide for writing manufacturing data on NXP devices](../../../../../guides/nxp/nxp_manufacturing_flow.md). +- To build the application with the OTA Requestor enabled, the arguments + `chip_enable_ota_requestor=true no_mcuboot=false` must be added to the _gn + gen_ command. (More information about the OTA Requestor feature in + [OTA Requestor README](../../../../../guides/nxp/nxp_rw61x_ota_software_update.md) + +## Manufacturing data + +See +[Guide for writing manufacturing data on NXP devices](../../../../../guides/nxp/nxp_manufacturing_flow.md) + +Other comments: + +The all cluster app demonstrates the usage of encrypted Matter manufacturing +data storage. Matter manufacturing data should be encrypted using an AES 128 +software key before flashing them to the device flash. + +Using DAC private key secure usage: Experimental feature, contain some +limitation: potential concurrent access issue during sign with dac key operation +due to the lack of protection between multiple access to `ELS` crypto module. +The argument `chip_enable_secure_dac_private_key_storage=1` must be added to the +_gn gen_ command to enable secure private DAC key usage with S50. +`chip_with_factory_data=1` must have been added to the _gn gen_ command + +DAC private key generation: The argument `chip_convert_dac_private_key=1` must +be added to the _gn gen_ command to enable DAC private plain key conversion to +blob with S50. `chip_enable_secure_dac_private_key_storage=1` must have been +added to the _gn gen_ command + +`ELS` contain concurrent access risks. They must be fixed before enabling it by +default. + + + +## Flashing and debugging + +### Flashing the All-Clusters application + +In order to flash the application we recommend using +[MCUXpresso IDE (version >= 11.6.0)](https://www.nxp.com/design/software/development-software/mcuxpresso-software-and-tools-/mcuxpresso-integrated-development-environment-ide:MCUXpresso-IDE). + +- Import the previously downloaded NXP SDK into MCUXpresso IDE. + +Right click the empty space in the MCUXpresso IDE "Installed SDKs" tab to show +the menu, select the "Import archive" (or "Import folder" if a folder is used) +menu item. + +- Import the connectedhomeip repo in MCUXpresso IDE as Makefile Project. Use + _none_ as _Toolchain for Indexer Settings_: + +``` +File -> Import -> C/C++ -> Existing Code as Makefile Project +``` + +- Configure MCU Settings: + +``` +Right click on the Project -> Properties -> C/C++ Build -> MCU Settings -> Select RW612 -> Apply & Close +``` + +![MCU_Set](../../../../../../../../examples/platform/nxp/rt/rw61x/doc/images/mcu-set.PNG) + +- Configure the toolchain editor: + +``` +Right click on the Project -> C/C++ Build-> Tool Chain Editor -> NXP MCU Tools -> Apply & Close +``` + +![toolchain](../../../../platform/nxp/rt/rw61x/doc/images/toolchain.JPG) + +- Create a debug configuration : + +``` +Right click on the Project -> Debug -> As->SEGGER JLink probes -> OK -> Select elf file +``` + +(Note : if SDK package is used, a simpler way could be duplicating the debug +configuration from the SDK Hello World example after importing it.) + +- Debug using the newly created configuration file. + + + +## Testing the example + +CHIP Tool is a Matter controller which can be used to commission a Matter device +into the network. For more information regarding how to use the CHIP Tool +controller, please refer to the +[CHIP Tool guide](../../../../../guides/chip_tool_guide.md). + +To know how to commission a device over BLE, follow the instructions from +[chip-tool's README.md 'Commission a device over +BLE'][readme_ble_commissioning_section]. + +[readme_ble_commissioning_section]: + ../../../../chip-tool/README.md#commission-a-device-over-ble + +To know how to commissioning a device over IP, follow the instructions from +[chip-tool's README.md 'Pair a device over +IP'][readme_pair_ip_commissioning_section] + +[readme_pair_ip_commissioning_section]: + ../../../../chip-tool/README.md#pair-a-device-over-ip + +#### Matter over wifi configuration : + +The "ble-wifi" pairing method can be used in order to commission the device. + +#### Matter over thread configuration : + +The "ble-thread" pairing method can be used in order to commission the device. + +#### Matter over wifi with openthread border router configuration : + +In order to create or join a Thread network on the Matter Border Router, the +`otcli` commands from the matter CLI can be used. For more information about +using the matter shell, follow instructions from +['Testing the all-clusters application with Matter CLI'](#testing-the-all-clusters-application-with-matter-cli-enabled). + +In this configuration, the device can be commissioned over Wi-Fi with the +'ble-wifi' pairing method. + +### Testing the all-clusters application without Matter CLI: + +1. Prepare the board with the flashed `All-cluster application` (as shown + above). +2. The All-cluster example uses UART1 (`FlexComm3`) to print logs while running + the server. To view raw UART output, start a terminal emulator like PuTTY and + connect to the used COM port with the following UART settings: + + - Baud rate: 115200 + - 8 data bits + - 1 stop bit + - No parity + - No flow control + +3. Open a terminal connection on the board and watch the printed logs. + +4. On the client side, start sending commands using the chip-tool application as + it is described + [here](../../../../chip-tool/README.md#using-the-client-to-send-matter-commands). + + + +### Testing the all-clusters application with Matter CLI enabled: + +The Matter CLI can be enabled with the all-clusters application. + +For more information about the Matter CLI default commands, you can refer to the +dedicated [ReadMe](../../../../shell/README.md). + +The All-clusters application supports additional commands : + +``` +> help +[...] +mattercommissioning Open/close the commissioning window. Usage : mattercommissioning [on|off] +matterfactoryreset Perform a factory reset on the device +matterreset Reset the device +``` + +- `matterfactoryreset` command erases the file system completely (all Matter + settings are erased). +- `matterreset` enables the device to reboot without erasing the settings. + +Here are described steps to use the all-cluster-app with the Matter CLI enabled + +1. Prepare the board with the flashed `All-cluster application` (as shown + above). +2. The matter CLI is accessible in UART1. For that, start a terminal emulator + like PuTTY and connect to the used COM port with the following UART settings: + + - Baud rate: 115200 + - 8 data bits + - 1 stop bit + - No parity + - No flow control + +3. The All-cluster example uses UART2 (`FlexComm0`) to print logs while running + the server. To view raw UART output, a pin should be plugged to an USB to + UART adapter (connector `HD2 pin 03`), then start a terminal emulator like + PuTTY and connect to the used COM port with the following UART settings: + + - Baud rate: 115200 + - 8 data bits + - 1 stop bit + - No parity + - No flow control + +4. On the client side, start sending commands using the chip-tool application as + it is described + [here](../../../../chip-tool/README.md#using-the-client-to-send-matter-commands). + +For Matter with OpenThread Border Router support, the matter CLI can be used to +start/join the Thread network, using the following ot-cli commands. (Note that +setting channel, panid, and network key is not enough anymore because of an Open +Thread stack update. We first need to initialize a new dataset.) + +``` +> otcli dataset init new +Done +> otcli dataset +Active Timestamp: 1 +Channel: 25 +Channel Mask: 0x07fff800 +Ext PAN ID: 42af793f623aab54 +Mesh Local Prefix: fd6e:c358:7078:5a8d::/64 +Network Key: f824658f79d8ca033fbb85ecc3ca91cc +Network Name: OpenThread-b870 +PAN ID: 0xb870 +PSKc: f438a194a5e968cc43cc4b3a6f560ca4 +Security Policy: 672 onrc 0 +Done +> otcli dataset panid 0xabcd +Done +> otcli dataset channel 25 +Done +> otcli dataset commit active +Done +> otcli ifconfig up +Done +> otcli thread start +Done +> otcli state +leader +Done +``` + + + +## OTA Software Update + +Over-The-Air software updates are supported with the RW61x all-clusters example. +The process to follow in order to perform a software update is described in the +dedicated guide +['Matter Over-The-Air Software Update with NXP RW61x example applications'](../../../../../guides/nxp/nxp_rw61x_ota_software_update.md). diff --git a/_sources/examples/all-clusters-app/openiotsdk/README.md b/_sources/examples/all-clusters-app/openiotsdk/README.md new file mode 100644 index 000000000000..8171e2101e02 --- /dev/null +++ b/_sources/examples/all-clusters-app/openiotsdk/README.md @@ -0,0 +1,100 @@ +# Matter Open IoT SDK All-Clusters-App Example Application + +The Open IoT SDK All Clusters Example demonstrates various ZCL clusters control. + +The example behaves as a Matter accessory, device that can be paired into an +existing Matter network and can be controlled by it. + +You can use this example as a reference for creating your own application. + +## Build-run-test-debug + +For information on how to build, run, test and debug this example and further +information about the platform it is run on see +[Open IoT SDK examples](../../../guides/openiotsdk_examples.md). + +The example name to use in the scripts is `all-clusters-app`. + +## Example output + +When the example runs, these lines should be visible: + +``` +[INF] [-] Open IoT SDK all-clusters-app example application start +... +[INF] [-] Open IoT SDK all-clusters-app example application run +``` + +This means the all-clusters-app application launched correctly and you can +follow traces in the terminal. + +### Commissioning + +Read the +[Open IoT SDK commissioning guide](../../../guides/openiotsdk_commissioning.md) +to see how to use the Matter controller to commission and control the +application. + +### AccessControl cluster usage + +The application fully supports the AccessControl cluster. For more details about +access control please visit +[Access Control Guide](../../../guides/access-control-guide.md). Use +cluster commands to trigger actions on the device. You can issue commands +through the same Matter controller you used to perform the commissioning step +above. + +Example command: + +``` +chip-tool accesscontrol read acl 123 0 +``` + +The numeric arguments are: device node ID and device endpoint ID, respectively. + +The device sent a response and you should see this line in the controller +output: + +``` +CHIP:TOO: Endpoint: 0 Cluster: 0x0000_001F Attribute 0x0000_0000 DataVersion: 3442030892 +CHIP:TOO: ACL: 1 entries +CHIP:TOO: [1]: { +CHIP:TOO: Privilege: 5 +CHIP:TOO: AuthMode: 2 +CHIP:TOO: Subjects: 1 entries +CHIP:TOO: [1]: 112233 +CHIP:TOO: Targets: null +CHIP:TOO: FabricIndex: 1 +CHIP:TOO: } +``` + +These are automatically installed ACL entries after commissioning. + +### BasicInformation cluster usage + +One of the fully supported clusters by this example is BasicInformation cluster. +Use cluster commands to trigger actions on the device. You can issue commands +through the same Matter controller you used to perform the commissioning step +above. + +Example command: + +``` +chip-tool basicinformation read vendor-id 123 0 +``` + +The numeric arguments are: device node ID and device endpoint ID, respectively. + +The device send a response with its vendor ID number and you should see this +line in the controller output: + +``` +CHIP:TOO: VendorID: 65521 +``` + +The `65521` value is the default `vendor ID` for Matter examples. + +**NOTE** + +More details about the `chip-tool` controller can be found +[here](../../chip-tool/README.md). diff --git a/_sources/examples/all-clusters-app/telink/README.md b/_sources/examples/all-clusters-app/telink/README.md new file mode 100644 index 000000000000..8b19db2888f4 --- /dev/null +++ b/_sources/examples/all-clusters-app/telink/README.md @@ -0,0 +1,181 @@ +# Matter Telink All Clusters Example Application + +The Telink All Clusters Example Application implements various ZCL clusters +populated on three endpoints. You can use this example as a reference for +creating your own application. + +![Telink B91 EVK](http://wiki.telink-semi.cn/wiki/assets/Hardware/B91_Generic_Starter_Kit_Hardware_Guide/connection_chart.png) + +## Build and flash + +1. Run the Docker container: + + ```bash + $ docker run -it --rm -v $PWD:/host -w /host ghcr.io/project-chip/chip-build-telink:$(wget -q -O - https://raw.githubusercontent.com/project-chip/connectedhomeip/master/.github/workflows/examples-telink.yaml 2> /dev/null | grep chip-build-telink | awk -F: '{print $NF}') + ``` + + Compatible docker image version can be found in next file: + + ```bash + $ .github/workflows/examples-telink.yaml + ``` + +2. Activate the build environment: + + ```bash + $ source ./scripts/activate.sh -p all,telink + ``` + +3. In the example dir run (replace __ with your board name, for + example, `tlsr9518adk80d`, `tlsr9528a` or `tlsr9258a`): + + ```bash + $ west build -b + ``` + + Also use key `-DFLASH_SIZE`, if your board has memory size different from 2 + MB, for example, `-DFLASH_SIZE=1m` or `-DFLASH_SIZE=4m`: + + ```bash + $ west build -b tlsr9518adk80d -- -DFLASH_SIZE=4m + ``` + +4. Flash binary: + + ``` + $ west flash --erase + ``` + +## Usage + +### UART + +To get output from device, connect UART to following pins: + +| Name | Pin | +| :--: | :---------------------------- | +| RX | PB3 (pin 17 of J34 connector) | +| TX | PB2 (pin 16 of J34 connector) | +| GND | GND | + +### Buttons + +The following buttons are available on **tlsr9518adk80d** board: + +| Name | Function | Description | +| :------- | :--------------------- | :----------------------------------------------------------------------------------------------------- | +| Button 1 | Factory reset | Perform factory reset to forget currently commissioned Thread network and back to uncommissioned state | +| Button 2 | Not used | Not used | +| Button 3 | Thread start | Commission thread with static credentials and enables the Thread on device | +| Button 4 | Open commission window | The button is opening commissioning window to perform commissioning over BLE | + +### LEDs + +#### Indicate current state of Thread network + +**Red** LED indicates current state of Thread network. It is able to be in +following states: + +| State | Description | +| :-------------------------- | :--------------------------------------------------------------------------- | +| Blinks with short pulses | Device is not commissioned to Thread, Thread is disabled | +| Blinks with frequent pulses | Device is commissioned, Thread enabled. Device trying to JOIN thread network | +| Blinks with wide pulses | Device commissioned and joined to thread network as CHILD | + +#### Indicate identify of device + +**Green** LED used to identify the device. The LED starts blinking when the +Identify command of the Identify cluster is received. The command's argument can +be used to specify the the effect. It is able to be in following effects: + +| Effect | Description | +| :------------------------------ | :--------------------------------------------------------------------------- | +| Blinks (200 ms on/200 ms off) | Blink (`Clusters::Identify::EffectIdentifierEnum::kBlink`) | +| Breathe (during 1000 ms) | Breathe (`Clusters::Identify::EffectIdentifierEnum::kBreathe`) | +| Blinks (50 ms on/950 ms off) | Okay (`Clusters::Identify::EffectIdentifierEnum::kOkay`) | +| Blinks (1000 ms on/1000 ms off) | Channel Change ( `Clusters::Identify::EffectIdentifierEnum::kChannelChange`) | +| Blinks (950 ms on/50 ms off) | Finish ( `Clusters::Identify::EffectIdentifierEnum::kFinishEffect`) | +| LED off | Stop (`Clusters::Identify::EffectIdentifierEnum::kStopEffect`) | + +### CHIP tool commands + +1. Build + [chip-tool cli](https://github.com/project-chip/connectedhomeip/blob/master/examples/chip-tool/README.md) + +2. Pair with device + + ``` + ${CHIP_TOOL_DIR}/chip-tool pairing ble-thread ${NODE_ID} hex:${DATASET} ${PIN_CODE} ${DISCRIMINATOR} + ``` + + Example: + + ``` + ./chip-tool pairing ble-thread 1234 hex:0e080000000000010000000300000f35060004001fffe0020811111111222222220708fd61f77bd3df233e051000112233445566778899aabbccddeeff030e4f70656e54687265616444656d6f010212340410445f2b5ca6f2a93a55ce570a70efeecb0c0402a0fff8 20202021 3840 + ``` + +### OTA with Linux OTA Provider + +OTA feature enabled by default only for ota-requestor-app example. To enable OTA +feature for another Telink example: + +- set CONFIG_CHIP_OTA_REQUESTOR=y in corresponding "prj.conf" configuration + file. + +After build application with enabled OTA feature, use next binary files: + +- zephyr.bin - main binary to flash PCB (Use at least 2MB PCB). +- zephyr-ota.bin - binary for OTA Provider + +All binaries has the same SW version. To test OTA “zephyr-ota.bin” should have +higher SW version than base SW. Set CONFIG_CHIP_DEVICE_SOFTWARE_VERSION=2 in +corresponding “prj.conf” configuration file. + +Usage of OTA: + +- Build the [Linux OTA Provider](https://github.com/project-chip/connectedhomeip/blob/master/examples/ota-provider-app/linux) + + ``` + ./scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/ota-provider-app chip_config_network_layer_ble=false + ``` + +- Run the Linux OTA Provider with OTA image. + + ``` + ./chip-ota-provider-app -f zephyr-ota.bin + ``` + +- Provision the Linux OTA Provider using chip-tool + + ``` + ./chip-tool pairing onnetwork ${OTA_PROVIDER_NODE_ID} 20202021 + ``` + + here: + + - \${OTA_PROVIDER_NODE_ID} is the node id of Linux OTA Provider + +- Configure the ACL of the ota-provider-app to allow access + + ``` + ./chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": null}]' ${OTA_PROVIDER_NODE_ID} 0 + ``` + + here: + + - \${OTA_PROVIDER_NODE_ID} is the node id of Linux OTA Provider + +- Use the chip-tool to announce the ota-provider-app to start the OTA process + + ``` + ./chip-tool otasoftwareupdaterequestor announce-otaprovider ${OTA_PROVIDER_NODE_ID} 0 0 0 ${DEVICE_NODE_ID} 0 + ``` + + here: + + - \${OTA_PROVIDER_NODE_ID} is the node id of Linux OTA Provider + - \${DEVICE_NODE_ID} is the node id of paired device + +Once the transfer is complete, OTA requestor sends ApplyUpdateRequest command to +OTA provider for applying the image. Device will restart on successful +application of OTA image. diff --git a/_sources/examples/all-clusters-minimal-app/ameba/README.md b/_sources/examples/all-clusters-minimal-app/ameba/README.md new file mode 100644 index 000000000000..82587a438f04 --- /dev/null +++ b/_sources/examples/all-clusters-minimal-app/ameba/README.md @@ -0,0 +1,153 @@ +# CHIP Ameba All Clusters Example + +A prototype application that demonstrates device commissioning and cluster +control. + +--- + +- [CHIP Ameba All Clusters Example](#chip-ameba-all-clusters-example) + - [Supported Device](#supported-device) + - [Building the Example Application](#building-the-example-application) + - [Commissioning and cluster control](#commissioning-and-cluster-control) + - [Commissioning](#commissioning) + - [BLE mode](#ble-mode) + - [IP mode](#ip-mode) + - [Cluster control](#cluster-control) + - [Running RPC Console](#running-rpc-console) + +--- + +## Supported Device + +The CHIP demo application is supported on +[Ameba RTL8722DM Board](https://www.amebaiot.com/en/amebad). + +## Building the Example Application + +- Pull docker image: + + ``` + $ docker pull ghcr.io/project-chip/chip-build-ameba:47 + ``` + +- Run docker container: + + ``` + $ docker run -it -v ${CHIP_DIR}:/root/chip ghcr.io/project-chip/chip-build-ameba:47 + ``` + +- Setup build environment: + + ``` + $ source ./scripts/bootstrap.sh + ``` + +- To build the demo application: + + ``` + $ ./scripts/build/build_examples.py --target ameba-amebad-all-clusters build + ``` + + The output image files are stored in + `out/ameba-amebad-all-clusters/asdk/image` folder. + + The bootloader image files are stored in + `out/ameba-amebad-all-clusters/asdk/bootloader` folder. + +- After building the application, **Ameba Image Tool** is used to flash it to + Ameba board. + +1. Connect your device via USB and open Ameba Image Tool. +2. Select correct serial port and set baudrate as **115200**. +3. Browse and add the corresponding image files in the Flash Download list to + the correct locations +4. Click **Download** button. + +## Commissioning and Cluster Control + +## Commissioning + +There are two commissioning modes supported by Ameba platform: + +### BLE mode + +1. In "connectedhomeip/config/ameba/args.gni" + + - Set `chip_config_network_layer_ble = true` + +2. In `connectedhomeip/src/platform/Ameba/CHIPDevicePlatformConfig.h` + + - Set `#define CHIP_DEVICE_CONFIG_ENABLE_CHIPOBLE 1` + +3. Build and Flash +4. The all-clusters example will run automatically after booting the Ameba + board. +5. Test with + [Chip-Tool](https://github.com/project-chip/connectedhomeip/tree/master/examples/chip-tool) + +### IP mode + +1. In `connectedhomeip/config/ameba/args.gni` + + - Set `chip_config_network_layer_ble = false` + +2. In `connectedhomeip/src/platform/Ameba/CHIPDevicePlatformConfig.h` + + - Set `#define CHIP_DEVICE_CONFIG_ENABLE_CHIPOBLE 0` + +3. Build and Flash +4. The all-clusters example will run automatically after booting the Ameba + board. +5. Connect to AP using `ATW0, ATW1, ATWC` commands +6. Test with + [Chip-Tool](https://github.com/project-chip/connectedhomeip/tree/master/examples/chip-tool) + +## Cluster Control + +After successful commissioning, use the OnOff cluster command to control the +OnOff attribute. This allows you to toggle a parameter implemented by the device +to be On or Off. + +- Via + [Chip-Tool](https://github.com/project-chip/connectedhomeip/tree/master/examples/chip-tool#using-the-client-to-send-matter-commands) + + ``` + $ ./chip-tool onoff on ${NODE_ID_TO_ASSIGN} 1 + $ ./chip-tool onoff off ${NODE_ID_TO_ASSIGN} 1 + ``` + +## Running RPC Console + +- Connect a USB-TTL Adapter as shown below + + ``` + Ameba USB-TTL + A19 TX + A18 RX + GND GND + ``` + +- Build the + [chip-rpc console](https://github.com/project-chip/connectedhomeip/tree/master/examples/common/pigweed/rpc_console) + +- As part of building the example with RPCs enabled the chip_rpc python + interactive console is installed into your venv. The python wheel files are + also created in the output folder: out/debug/chip_rpc_console_wheels. To + install the wheel files without rebuilding: + + ``` + $ pip3 install out/debug/chip_rpc_console_wheels/*.whl + ``` + +- Launch the chip-rpc console after resetting Ameba board + + ``` + $ chip-console --device /dev/tty -b 115200 + ``` + +- Get and Set lighting directly using the RPC console + + ```python + rpcs.chip.rpc.Lighting.Get() + rpcs.chip.rpc.Lighting.Set(on=True, level=128, color=protos.chip.rpc.LightingColor(hue=5, saturation=5)) + ``` diff --git a/_sources/examples/all-clusters-minimal-app/asr/README.md b/_sources/examples/all-clusters-minimal-app/asr/README.md new file mode 100644 index 000000000000..09b582e49d5e --- /dev/null +++ b/_sources/examples/all-clusters-minimal-app/asr/README.md @@ -0,0 +1,35 @@ +# Matter ASR All Clusters Example + +A prototype application that demonstrates device commissioning and cluster +control on ASR platform. + +--- + +- [Matter ASR All Clusters Example](#matter-asr-all-clusters-example) + - [Building and Commissioning](#building-and-commissioning) + - [Cluster Control](#cluster-control) + +--- + +## Building and Commissioning + +Please refer +[Building and Commissioning](../../../guides/asr_getting_started_guide.md#building-the-example-application) +guides to get started + +``` +./scripts/build/build_examples.py --target asr-$ASR_BOARD-all-clusters-minimal build +``` + +## Cluster Control + +After successful commissioning, use `chip-tool` to control the board + +For example,control the OnOff Cluster attribute: + +``` +./chip-tool onoff read on-off 1 +./chip-tool onoff on 1 +./chip-tool onoff off 1 +./chip-tool onoff toggle 1 +``` diff --git a/_sources/examples/all-clusters-minimal-app/esp32/README.md b/_sources/examples/all-clusters-minimal-app/esp32/README.md new file mode 100644 index 000000000000..3dd93ba6f118 --- /dev/null +++ b/_sources/examples/all-clusters-minimal-app/esp32/README.md @@ -0,0 +1,51 @@ +# CHIP ESP32 All Clusters Example + +A prototype application that demonstrates device commissioning and cluster +control. + +Please +[setup ESP-IDF and CHIP Environment](../../../guides/esp32/setup_idf_chip.md) +and refer +[building and commissioning](../../../guides/esp32/build_app_and_commission.md) +guides to get started. + +--- + +- [Cluster control](#cluster-control) +- [Matter OTA guide](../../../guides/esp32/ota.md) +- [RPC console and Device Tracing](../../../guides/esp32/rpc_console.md) + +--- + +### Cluster control + +#### onoff + +To use the Client to send Matter commands, run the built executable and pass it +the target cluster name, the target command name as well as an endpoint id. + +``` +$ ./out/debug/chip-tool onoff on +``` + +The client will send a single command packet and then exit. + +#### levelcontrol + +```bash +Usage: + $ ./out/debug/chip-tool levelcontrol move-to-level Level=10 TransitionTime=0 OptionMask=0 OptionOverride=0 +``` + +--- + +This demo app illustrates controlling OnOff cluster (Server) attributes of an +endpoint. For `ESP32-DevKitC`, `ESP32-WROVER-KIT_V4.1` and `ESP32C3-DevKitM`, a +GPIO (configurable through `STATUS_LED_GPIO_NUM` in `main/main.cpp`) is updated +through the on/off/toggle commands from the `python-controller`. For `M5Stack`, +a virtual Green LED on the display is used for the same. + +If you wish to see the actual effect of the commands on `ESP32-DevKitC`, +`ESP32-WROVER-KIT_V4.1`, you will have to connect an external LED to GPIO +`STATUS_LED_GPIO_NUM`. For `ESP32C3-DevKitM`, the on-board LED will show the +actual effect of the commands. diff --git a/_sources/examples/all-clusters-minimal-app/infineon/psoc6/README.md b/_sources/examples/all-clusters-minimal-app/infineon/psoc6/README.md new file mode 100644 index 000000000000..d072e10790b8 --- /dev/null +++ b/_sources/examples/all-clusters-minimal-app/infineon/psoc6/README.md @@ -0,0 +1,127 @@ +# CHIP PSoC6 All Clusters Example + +An example showing the use of Matter on the Infineon CY8CKIT-062S2-43012 board. + +
    + +- [Matter PSoC6 All Clusters Example](#chip-psoc6-all-clusters-example) + - [Introduction](#introduction) + - [Building](#building) + - [Flashing the Application](#flashing-the-application) + - [Commissioning and cluster control](#commissioning-and-cluster-control) + - [Setting up chip-tool](#setting-up-chip-tool) + - [Commissioning over BLE](#commissioning-over-ble) + - [Notes](#notes) + - [Factory Reset](#factory-reset) + - [OTA Software Update](#ota-software-update) + +
    + +## Introduction + +The PSoC6 clusters example provides a baseline demonstration of a Cluster +control device, built using Matter and the Infineon Modustoolbox SDK. It can be +controlled by Matter controller over Wi-Fi network. + +The PSoC6 device can be commissioned over Bluetooth Low Energy where the device +and the Matter controller will exchange security information with the Rendezvous +procedure. Wi-Fi Network credentials are then provided to the PSoC6 device which +will then join the network. + +## Building + +- [Modustoolbox Software](https://www.cypress.com/products/modustoolbox) + + Refer to `integrations/docker/images/chip-build-infineon/Dockerfile` or + `scripts/examples/gn_psoc6_example.sh` for downloading the Software and + related tools. + +- Install some additional tools (likely already present for Matter + developers): + + ``` + sudo apt install gcc g++ clang ninja-build python \ + python3-venv libssl-dev libavahi-client-dev libglib2.0-dev git cmake \ + python3-pip + ``` + +- Supported hardware: + [CY8CKIT-062S2-43012](https://www.cypress.com/CY8CKIT-062S2-43012) + +* Build the example application: + + $ source scripts/activate.sh + $ scripts/build/build_examples.py --no-log-timestamps --target 'infineon-psoc6-all-clusters-minimal' build + +- To delete generated executable, libraries and object files use: + + $ cd ~/connectedhomeip + $ rm -rf out/ + +## Flashing the Application + +- Put CY8CKIT-062S2-43012 board on KitProg3 CMSIS-DAP Mode by pressing the + `MODE SELECT` button. `KITPROG3 STATUS` LED is ON confirms board is in + proper mode. + +- On the command line: + + $ cd ~/connectedhomeip + $ python3 out/infineon-psoc6-all-clusters-minimal/chip-psoc6-clusters-minimal-example.flash.py + +## Commissioning and cluster control + +Commissioning can be carried out using BLE. + +### Setting up Chip tool + +Once PSoC6 is up and running, we need to set up chip-tool on Raspberry Pi 4 to +perform commissioning and cluster control. + +- Set up python controller. + + $ cd {path-to-connectedhomeip} + $ ./scripts/examples/gn_build_example.sh examples/chip-tool out/debug + +- Execute the controller. + + $ ./out/debug/chip-tool + +### Commissioning over BLE + +Run the built executable and pass it the discriminator and pairing code of the +remote device, as well as the network credentials to use. + + $ ./out/debug/chip-tool pairing ble-wifi 1234 ${SSID} ${PASSWORD} 20202021 3840 + + Parameters: + 1. Discriminator: 3840 + 2. Setup-pin-code: 20202021 + 3. Node ID: 1234 (you can assign any node id) + 4. SSID : Wi-Fi SSID + 5. PASSWORD : Wi-Fi Password + +#### Notes + +Raspberry Pi 4 BLE connection issues can be avoided by running the following +commands. These power cycle the BlueTooth hardware and disable BR/EDR mode. + + $ sudo btmgmt -i hci0 power off + $ sudo btmgmt -i hci0 bredr off + $ sudo btmgmt -i hci0 power on + +### Factory Reset + +- Commissioned Wi-Fi Credentials can be cleared by pressing `USER_BTN2` button + on the board. All the data configured on the device during the initial + commissioning will be deleted and device will be ready for commissioning + again. + +- Pressing the button again within 5 seconds will cancel the factory reset of + the board. + +## OTA Software Update + +For the description of Software Update process with infineon PSoC6 example +applications see +[Infineon PSoC6 OTA Software Update](../../../../guides/infineon_psoc6_software_update.md) diff --git a/_sources/examples/all-clusters-minimal-app/mbed/README.md b/_sources/examples/all-clusters-minimal-app/mbed/README.md new file mode 100644 index 000000000000..a2c4aab74c64 --- /dev/null +++ b/_sources/examples/all-clusters-minimal-app/mbed/README.md @@ -0,0 +1,277 @@ +![ARM Mbed-OS logo](https://raw.githubusercontent.com/ARMmbed/mbed-os/master/logo.png) + +# Matter Arm Mbed OS All Clusters Example Application + +The Arm Mbed OS All Clusters Example demonstrates device commissioning process +and all available clusters control. + +You can use this example as a reference for creating your own application. + +The example is based on +[Matter](https://github.com/project-chip/connectedhomeip) and Arm Mbed OS, and +supports remote access and control of device over a WiFi network. + +The example behaves as a Matter accessory, in other words a device that can be +paired into an existing Matter network and can be controlled by this network. + +
    + +- [Overview](#overview) + - [Bluetooth Low Energy advertising](#bluetooth-low-energy-advertising) + - [Bluetooth Low Energy rendezvous](#bluetooth-low-energy-rendezvous) + - [WiFi provisioning](#wifi-provisioning) +- [Run application](#run-application) + - [Environment setup](#environment-setup) + - [Building](#building) + - [Flashing](#flashing) + - [Debugging](#debugging) + - [Testing](#testing) + - [Serial port terminal](#serial-port-terminal) + - [CHIP Tools](#chip-tools) + - [Supported devices](#supported-devices) + - [Notes](#notes) +- [Device UI](#device-ui) + - [Notes](#notes-1) + +
    + +# Overview + +The Matter device that runs the All Clusters application is controlled by the +Matter controller device over WiFi. By default, the Matter device is +disconnected, and it should be paired with Matter controller and get +configuration from it. Actions required before establishing full communication +are described below. + +## Bluetooth Low Energy advertising + +To commission the device onto a Matter network, the device must be discoverable +over BLE. The BLE advertising starts automatically after device boot-up. + +## Bluetooth Low Energy rendezvous + +In Matter, the commissioning procedure (called rendezvous) is done over BLE +between a Matter device and the Matter controller, where the controller has the +commissioner role. + +To start the rendezvous, the controller must get the commissioning information +from the Matter device. The data payload is encoded within a QR code, printed to +the UART console. + +## WiFi provisioning + +The last part of the rendezvous procedure, provisioning involves sending the +network credentials from the Matter controller to the Matter device. As a +result, device is able to join the network and communicate with other devices in +the network. + +# Run application + +## Environment setup + +Before building the example, check out the Matter repository and sync submodules +using the following command: + + $ git submodule update --init + +Building the example application requires the use of **ARM Mbed-OS** sources and +the **arm-none-gnu-eabi** toolchain. + +The Cypress OpenOCD package is required for flashing purpose. Install the +Cypress OpenOCD and set env var `OPENOCD_PATH` before calling the flashing +script. + +``` +cd ~ +wget https://github.com/Infineon/openocd/releases/download/release-v4.3.0/openocd-4.3.0.1746-linux.tar.gz +tar xzvf openocd-4.3.0.1746-linux.tar.gz +export OPENOCD_PATH=$HOME/openocd +``` + +Some additional packages may be needed, depending on selected build target and +its requirements. + +> **The VSCode devcontainer has these components pre-installed. Using the VSCode +> devcontainer is the recommended way to interact with Arm Mbed-OS port of the +> Matter Project.** +> +> **Please read this [README.md](../../../VSCODE_DEVELOPMENT.md) for more +> information about using VSCode in container.** + +To initialize the development environment, download all registered sub-modules +and activate the environment: + +``` +$ source ./scripts/bootstrap.sh +$ source ./scripts/activate.sh +``` + +If packages are already installed then you just need to activate the development +environment: + +``` +$ source ./scripts/activate.sh +``` + +## Building + +The All Clusters application can be built in the same way as any other Matter +example ported to the mbed-os platform. + +- **by using generic vscode task**: + +``` +Command Palette (F1) => Run Task... => Run Mbed Application => build => all-clusters-minimal-app => (board name) => (build profile) => (build type) +``` + +- **by calling explicitly building script:** + +``` +${MATTER_ROOT}/scripts/examples/mbed_example.sh -c=build -a=all-clusters-minimal-app -b= -p= -T= +``` + +Both approaches are limited to supported evaluation boards which are listed in +[Supported devices](#supported-devices) paragraph. + +Mbed OS defines three building profiles: _develop, debug_ and _release_. For +more details please visit +[ARM Mbed OS build profiles](https://os.mbed.com/docs/mbed-os/latest/program-setup/build-profiles-and-rules.html). + +There are also three types of built application: _simple, boot_ and _upgrade_: + +- **simple** - standalone application, mainly for developing and testing + purpose (all building profiles are supported) +- **boot** - signed application + bootloader, it supports booting process and + can be use for firmware update (only _release_ building profiles is + supported) +- **update** - signed application, application image can be used for firmware + update (only _release_ building profiles is supported) + +When using the building script, it is possible expand the list of acceptable +targets; this may be useful for rapid testing of a new mbed-targets. + +## Flashing + +The All Clusters application can be flashed in the same way as any other Matter +example ported to mbed-os platform. + +The [Open On-Chip Debugger](http://openocd.org/) is used to upload a binary +image and reset the device. + +- **by using VSCode task**: + +``` +Command Palette (F1) => Run Task... -> Run Mbed Application => flash => all-clusters-minimal-app => (board name) => (build profile) +``` + +- **by calling explicitly building script:** + +``` +${MATTER_ROOT}/scripts/examples/mbed_example.sh -c=flash -a=all-clusters-minimal-app -b= -p= +``` + +- **by using VSCode launch task**: + +``` +Run and Debug (Ctrl+Shift+D) => Flash Mbed examples => Start Debugging (F5) => (board name) => all-clusters-minimal-app => (build profile) +``` + +The last option uses the Open On-Chip Debugger to open and manage the gdb-server +session. Then gdb-client (arm-none-eabi-gdb) upload binary image and reset +device. + +It is possible to connect to an external gdb-server session by using a specific +**'Flash Mbed examples [remote]'** task. + +## Debugging + +Debugging can be performed in the same was as with any other Matter example +ported to mbed-os platform. + +The [Open On-Chip Debugger](http://openocd.org/) is used to to open and manage +the gdb-server session. Then gdb-client (arm-none-eabi-gdb) connect the server +to upload binary image and control debugging. + +``` +Run and Debug (Ctrl+Shift+D) => Debug Mbed examples => Start Debugging (F5) => (board name) => all-clusters-minimal-app => (build profile) +``` + +It is possible to connect to an external gdb-server session by using specific +**'Debug Mbed examples [remote]'** task. + +## Testing + +### Serial port terminal + +The application traces are streaming to serial output. To start communication +open a terminal session and connect to the serial port of the device. You can +use **mbed-tools** for this purpose +([mbed-tools](https://github.com/ARMmbed/mbed-tools)): + + ``` + mbed-tools sterm -p /dev/ttyACM0 -b 115200 -e off + ``` + +After device reset these lines should be visible: + + ``` + [INFO][CHIP]: [-]Mbed all-clusters-minimal-app example application start + ... + [INFO][CHIP]: [-]Mbed all-clusters-minimal-app example application run + ``` + +The all-clusters-minimal-app application launched correctly and you can follow +traces in the terminal. + +### CHIP Tools + +Read the [MbedCommissioning](../../../guides/mbedos_commissioning.md) to +see how to use different CHIP tools to commission and control the application +within a WiFi network. + +## Supported devices + +| Manufacturer | Hardware platform | Build target | Platform image | Status | Platform components | +| ----------------------------------------------------- | ------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------ | :----: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Cypress
    Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` | ![CY8CPROTO-062-4343W](https://os.mbed.com/media/cache/platforms/p6_wifi-bt_proto.png.250x250_q85.jpg) | ✔ |
    LEDs
    • Board has only one usable LED (LED4) which corresponds to USER LED from UI.
    Buttons
    • Unused
    Slider
    • Unused
    | + +#### Notes + +- More details and guidelines about porting new hardware into the Matter + project with Mbed OS can be found in + [MbedNewTarget](../../../guides/mbedos_add_new_target.md) +- Some useful information about HW platform specific settings can be found in + `all-clusters-minimal-app/mbed/mbed_app.json`. + Information about this file syntax and its meaning in mbed-os project can be + found here: + [Mbed-Os configuration system](https://os.mbed.com/docs/mbed-os/latest/program-setup/advanced-configuration.html)) + +# Device UI + +This section lists the User Interface elements that you can use to control and +monitor the state of the device. These correspond to PCB components on the +platform image. + +**USER LED** shows the overall state of the device and its connectivity. The +following states are possible: + +- _Short Flash On (50 ms on/950 ms off)_ — The device is in the + unprovisioned (unpaired) state and is waiting for a commissioning + application to connect. + +- _Rapid Even Flashing (100 ms on/100 ms off)_ — The device is in the + unprovisioned state and a commissioning application is connected through + Bluetooth LE. + +- _Short Flash Off (950ms on/50ms off)_ — The device is fully + provisioned, but does not yet have full network or service connectivity. + +- _Solid On_ — The device is fully provisioned and has full network and + service connectivity. + +### Notes + +Some of the supported boards may not have sufficient number PCB components to +follow above description. In that case please refer to +[Supported devices](#supported-devices) section and check board's 'Platform +components' column for additional information about the limitation. diff --git a/_sources/examples/all-clusters-minimal-app/nrfconnect/README.md b/_sources/examples/all-clusters-minimal-app/nrfconnect/README.md new file mode 100644 index 000000000000..9e9443417b60 --- /dev/null +++ b/_sources/examples/all-clusters-minimal-app/nrfconnect/README.md @@ -0,0 +1,406 @@ +# Matter nRF Connect All Clusters Example Application + +The nRF All Clusters Example Application implements various ZCL clusters +populated on three endpoints. You can use this example as a reference for +creating your own application. + +![Nordic Smiconductor logo](../../platform/nrfconnect/doc/images/Logo_RGB_H-small.png) +![nRF52840 DK](../../platform/nrfconnect/doc/images/nRF52840-DK-small.png) + +The example is based on +[Matter](https://github.com/project-chip/connectedhomeip) and Nordic +Semiconductor's nRF Connect SDK, and was created to facilitate testing and +certification of a Matter device communicating over a low-power, 802.15.4 Thread +network. + +The example behaves as a Matter accessory, that is a device that can be paired +into an existing Matter network and can be controlled by this network. The +device works as a Thread Minimal End Device. + +
    + +## Overview + +This example is running on the nRF Connect platform, which is based on Nordic +Semiconductor's +[nRF Connect SDK](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/index.html) +and [Zephyr RTOS](https://zephyrproject.org/). Visit Matter's +[nRF Connect platform overview](../../../guides/nrfconnect_platform_overview.md) +to read more about the platform structure and dependencies. + +By default, the Matter accessory device has IPv6 networking disabled. You must +pair it with the Matter controller over Bluetooth® LE to get the configuration +from the controller to use the device within a Thread or Wi-Fi network. You have +to make the device discoverable manually (for security reasons). See +[Bluetooth LE advertising](#bluetooth-le-advertising) to learn how to do this. +The controller must get the commissioning information from the Matter accessory +device and provision the device into the network. + +You can test this application remotely over the Thread or the Wi-Fi protocol, +which in either case requires more devices, including a Matter controller that +you can configure either on a PC or a mobile device. + +### Bluetooth LE advertising + +In this example, to commission the device onto a Matter network, it must be +discoverable over Bluetooth LE. For security reasons, you must start Bluetooth +LE advertising manually after powering up the device by pressing **Button 4**. + +### Bluetooth LE rendezvous + +In this example, the commissioning procedure is done over Bluetooth LE between a +Matter device and the Matter controller, where the controller has the +commissioner role. + +To start the rendezvous, the controller must get the commissioning information +from the Matter device. The data payload is encoded within a QR code, printed to +the UART console. + +#### Thread provisioning + +Last part of the rendezvous procedure, the provisioning operation involves +sending the Thread network credentials from the Matter controller to the Matter +device. As a result, device is able to join the Thread network and communicate +with other Thread devices in the network. + +
    + +## Requirements + +The application requires a specific revision of the nRF Connect SDK to work +correctly. See [Setting up the environment](#setting-up-the-environment) for +more information. + +### Supported devices + +The example supports building and running on the following devices: + +| Hardware platform | Build target | Platform image | +| ------------------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [nRF52840 DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK) | `nrf52840dk_nrf52840` |
    nRF52840 DKnRF52840 DK
    | +| [nRF5340 DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF5340-DK) | `nrf5340dk_nrf5340_cpuapp` |
    nRF5340 DKnRF5340 DK
    | +| [nRF52840 Dongle](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-Dongle) | `nrf52840dongle_nrf52840` |
    nRF52840 DonglenRF52840 Dongle
    | + +
    + +## Device UI + +This section lists the User Interface elements that you can use to control and +monitor the state of the device. These correspond to PCB components on the +platform image. + +> **Note**: +> +> The following Device UI elements are missing on the nRF52840 Dongle: **Button +> 2**, **Button 3**, **Button 4**, **SEGGER J-Link USB port**, and **NFC port +> with antenna attached**. You can collect logs from the nRF52840 Dongle using +> the **nRF USB port** instead of the **SEGGER J-Link USB port**. +> Functionalities associated with the remaining missing elements are +> inaccessible. + +**LED 1** shows the overall state of the device and its connectivity. The +following states are possible: + +- _Short Flash On (50 ms on/950 ms off)_ — The device is in the + unprovisioned (unpaired) state and is waiting for a commissioning + application to connect. + +- _Rapid Even Flashing (100 ms on/100 ms off)_ — The device is in the + unprovisioned state and a commissioning application is connected through + Bluetooth LE. + +- _Short Flash Off (950ms on/50ms off)_ — The device is fully + provisioned, but does not yet have full connectivity for Thread or Wi-Fi + network, or the related services. + +- _Solid On_ — The device is fully provisioned and has full Thread + network and service connectivity. + +**Button 1** can be used for the following purposes: + +- _Pressed for 6 s_ — Initiates the factory reset of the device. + Releasing the button within the 6-second window cancels the factory reset + procedure. **LEDs 1-4** blink in unison when the factory reset procedure is + initiated. + +**Button 4** — Pressing the button once starts Bluetooth LE advertising +for the predefined period of time (15 minutes by default). + +**SEGGER J-Link USB port** can be used to get logs from the device or +communicate with it using the +[command line interface](../../../guides/nrfconnect_examples_cli.md). + +
    + +## Setting up the environment + +Before building the example, check out the Matter repository and sync submodules +using the following command: + + $ git submodule update --init + +The example requires a specific revision of the nRF Connect SDK. You can either +install it along with the related tools directly on your system or use a Docker +image that has the tools pre-installed. + +If you are a macOS user, you won't be able to use the Docker container to flash +the application onto a Nordic development kit due to +[certain limitations of Docker for macOS](https://docs.docker.com/docker-for-mac/faqs/#can-i-pass-through-a-usb-device-to-a-container). +Use the [native shell](#using-native-shell-for-setup) for building instead. + +### Using Docker container for setup + +To use the Docker container for setup, complete the following steps: + +1. If you do not have the nRF Connect SDK installed yet, create a directory for + it by running the following command: + + $ mkdir ~/nrfconnect + +2. Download the latest version of the nRF Connect SDK Docker image by running + the following command: + + $ docker pull nordicsemi/nrfconnect-chip + +3. Start Docker with the downloaded image by running the following command, + customized to your needs as described below: + + $ docker run --rm -it -e RUNAS=$(id -u) -v ~/nrfconnect:/var/ncs -v ~/connectedhomeip:/var/chip \ + -v /dev/bus/usb:/dev/bus/usb --device-cgroup-rule "c 189:* rmw" nordicsemi/nrfconnect-chip + + In this command: + + - _~/nrfconnect_ can be replaced with an absolute path to the nRF Connect + SDK source directory. + - _~/connectedhomeip_ must be replaced with an absolute path to the CHIP + source directory. + - _-v /dev/bus/usb:/dev/bus/usb --device-cgroup-rule "c 189:_ rmw"\* + parameters can be omitted if you are not planning to flash the example + onto hardware. These parameters give the container access to USB devices + connected to your computer such as the nRF52840 DK. + - _--rm_ can be omitted if you do not want the container to be + auto-removed when you exit the container shell session. + - _-e RUNAS=\$(id -u)_ is needed to start the container session as the + current user instead of root. + +4. Update the nRF Connect SDK to the most recent supported revision, by running + the following command: + + $ cd /var/chip + $ python3 scripts/setup/nrfconnect/update_ncs.py --update + +Now you can proceed with the [Building](#building) instruction. + +### Using native shell for setup + +To use the native shell for setup, complete the following steps: + +1. Download and install the following additional software: + + - [nRF Command Line Tools](https://www.nordicsemi.com/Software-and-Tools/Development-Tools/nRF-Command-Line-Tools) + - [GN meta-build system](https://gn.googlesource.com/gn/) + +2. If you do not have the nRF Connect SDK installed, follow the + [guide](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/gs_assistant.html#) + in the nRF Connect SDK documentation to install the latest stable nRF + Connect SDK version. Since command-line tools will be used for building the + example, installing SEGGER Embedded Studio is not required. + + If you have the SDK already installed, continue to the next step and update + the nRF Connect SDK after initializing environment variables. + +3. Initialize environment variables referred to by the CHIP and the nRF Connect + SDK build scripts. Replace _nrfconnect-dir_ with the path to your nRF + Connect SDK installation directory, and _toolchain-dir_ with the path to GNU + Arm Embedded Toolchain. + + $ source nrfconnect-dir/zephyr/zephyr-env.sh + $ export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb + $ export GNUARMEMB_TOOLCHAIN_PATH=toolchain-dir + +4. Update the nRF Connect SDK to the most recent supported revision by running + the following command (replace _matter-dir_ with the path to Matter + repository directory): + + $ cd matter-dir + $ python3 scripts/setup/nrfconnect/update_ncs.py --update + +Now you can proceed with the [Building](#building) instruction. + +
    + +## Building + +Complete the following steps, regardless of the method used for setting up the +environment: + +1. Navigate to the example's directory: + + $ cd examples/all-clusters-minimal-app/nrfconnect + +2. Run the following command to build the example, with _build-target_ replaced + with the build target name of the Nordic Semiconductor's kit you own, for + example `nrf52840dk_nrf52840`: + + $ west build -b build-target + + You only need to specify the build target on the first build. See + [Requirements](#requirements) for the build target names of compatible kits. + +The output `zephyr.hex` file will be available in the `build/zephyr/` directory. + +### Removing build artifacts + +If you're planning to build the example for a different kit or make changes to +the configuration, remove all build artifacts before building. To do so, use the +following command: + + $ rm -r build + +### Building with release configuration + +To build the example with release configuration that disables the diagnostic +features like logs and command-line interface, run the following command: + + $ west build -b build-target -- -DCONF_FILE=prj_release.conf + +Remember to replace _build-target_ with the build target name of the Nordic +Semiconductor's kit you own. + +### Building with Device Firmware Upgrade support + +Support for DFU using Matter OTA is disabled by default. + +To build the example with configuration that supports DFU, run the following +command with _build-target_ replaced with the build target name of the Nordic +Semiconductor kit you are using (for example `nrf52840dk_nrf52840`): + + $ west build -b build-target -- -DCONF_FILE=prj_dfu.conf + +> **Note**: +> +> There are two types of Device Firmware Upgrade modes: single-image DFU and +> multi-image DFU. Single-image mode supports upgrading only one firmware image, +> the application image, and should be used for single-core nRF52840 DK devices. +> Multi-image mode allows to upgrade more firmware images and is suitable for +> upgrading the application core and network core firmware in two-core nRF5340 +> DK devices. +> +> Currently the multi-image mode is not available for the Matter OTA DFU. + +#### Changing bootloader configuration + +To change the default MCUboot configuration, edit the `prj.conf` file located in +the `child_image/mcuboot` directory. + +#### Changing flash memory settings + +In the default configuration, the MCUboot uses the +[Partition Manager](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/scripts/partition_manager/partition_manager.html#partition-manager) +to configure flash partitions used for the bootloader application image slot +purposes. You can change these settings by defining +[static partitions](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/scripts/partition_manager/partition_manager.html#ug-pm-static). +This example uses this option to define using an external flash. + +To modify the flash settings of your board (that is, your _build-target_, for +example `nrf52840dk_nrf52840`), edit the `pm_static_dfu.yml` file located in the +`configuration/build-target/` directory. + +
    + +## Configuring the example + +The Zephyr ecosystem is based on Kconfig files and the settings can be modified +using the menuconfig utility. + +To open the menuconfig utility, run the following command from the example +directory: + + $ west build -b build-target -t menuconfig + +Remember to replace _build-target_ with the build target name of the Nordic +Semiconductor's kit you own. + +Changes done with menuconfig will be lost if the `build` directory is deleted. +To make them persistent, save the configuration options in the `prj.conf` file. + +### Example build types + +The example uses different configuration files depending on the supported +features. Configuration files are provided for different build types and they +are located in the application root directory. + +The `prj.conf` file represents a debug build type. Other build types are covered +by dedicated files with the build type added as a suffix to the prj part, as per +the following list. For example, the release build type file name is +`prj_release.conf`. If a board has other configuration files, for example +associated with partition layout or child image configuration, these follow the +same pattern. + +Before you start testing the application, you can select one of the build types +supported by the sample. This sample supports the following build types, +depending on the selected board: + +- debug -- Debug version of the application - can be used to enable additional + features for verifying the application behavior, such as logs or + command-line shell. +- release -- Release version of the application - can be used to enable only + the necessary application functionalities to optimize its performance. It + has Device Firmware Upgrade feature enabled. It can be used only for the + nRF52840 DK and nRF5340 DK, as only those platforms support the DFU. +- dfu -- Debug version of the application with Device Firmware Upgrade feature + support. It can be used only for the nRF52840 DK and nRF5340 DK, as only + those platforms support the DFU. + +For more information, see the +[Configuring nRF Connect SDK examples](../../../guides/nrfconnect_examples_configuration.md) +page. + +
    + +## Flashing and debugging + +The flashing and debugging procedure is different for the development kits and +the nRF52840 Dongle. + +### Flashing on the development kits + +To flash the application to the device, use the west tool and run the following +command from the example directory: + + $ west flash --erase + +If you have multiple development kits connected, west will prompt you to pick +the correct one. + +To debug the application on target, run the following command from the example +directory: + + $ west debug + +### Flashing on the nRF52840 Dongle + +Visit +[Programming and Debugging nRF52840 Dongle](https://docs.zephyrproject.org/latest/boards/arm/nrf52840dongle_nrf52840/doc/index.html#programming-and-debugging) +to read more about flashing on the nRF52840 Dongle. + +
    + +## Testing the example + +Check the [CLI tutorial](../../../guides/nrfconnect_examples_cli.md) to +learn how to use command-line interface of the application. + +### Testing using Linux CHIPTool + +Read the [CHIP Tool user guide](../../../guides/chip_tool_guide.md) to see +how to use [CHIP Tool for Linux or mac OS](../../chip-tool/README.md) to +commission and control the application within a Matter-enabled Thread network. + +### Testing using Android CHIPTool + +Read the +[Android commissioning guide](../../../guides/nrfconnect_android_commissioning.md) +to see how to use [CHIPTool](https://github.com/project-chip/connectedhomeip/blob/master/examples/android/CHIPTool/README.md) for +Android smartphones to commission and control the application within a +Matter-enabled Thread network. diff --git a/_sources/examples/all-clusters-minimal-app/telink/README.md b/_sources/examples/all-clusters-minimal-app/telink/README.md new file mode 100644 index 000000000000..fc47e30f4dfd --- /dev/null +++ b/_sources/examples/all-clusters-minimal-app/telink/README.md @@ -0,0 +1,164 @@ +# Matter Telink All Clusters Minimal Example Application + +The Telink All Clusters Minimal Example Application implements various ZCL +clusters populated on three endpoints. You can use this example as a reference +for creating your own application. + +![Telink B91 EVK](http://wiki.telink-semi.cn/wiki/assets/Hardware/B91_Generic_Starter_Kit_Hardware_Guide/connection_chart.png) + +## Build and flash + +1. Run the Docker container: + + ```bash + $ docker run -it --rm -v $PWD:/host -w /host ghcr.io/project-chip/chip-build-telink:$(wget -q -O - https://raw.githubusercontent.com/project-chip/connectedhomeip/master/.github/workflows/examples-telink.yaml 2> /dev/null | grep chip-build-telink | awk -F: '{print $NF}') + ``` + + Compatible docker image version can be found in next file: + + ```bash + $ .github/workflows/examples-telink.yaml + ``` + +2. Activate the build environment: + + ```bash + $ source ./scripts/activate.sh -p all,telink + ``` + +3. In the example dir run (replace __ with your board name, for + example, `tlsr9518adk80d`, `tlsr9528a` or `tlsr9258a`): + + ```bash + $ west build -b + ``` + + Also use key `-DFLASH_SIZE`, if your board has memory size different from 2 + MB, for example, `-DFLASH_SIZE=1m` or `-DFLASH_SIZE=4m`: + + ```bash + $ west build -b tlsr9518adk80d -- -DFLASH_SIZE=4m + ``` + +4. Flash binary: + + ``` + $ west flash --erase + ``` + +## Usage + +### UART + +To get output from device, connect UART to following pins: + +| Name | Pin | +| :--: | :---------------------------- | +| RX | PB3 (pin 17 of J34 connector) | +| TX | PB2 (pin 16 of J34 connector) | +| GND | GND | + +### Buttons + +The following buttons are available on **tlsr9518adk80d** board: + +| Name | Function | Description | +| :------- | :--------------------- | :----------------------------------------------------------------------------------------------------- | +| Button 1 | Factory reset | Perform factory reset to forget currently commissioned Thread network and back to uncommissioned state | +| Button 2 | Not used | Not used | +| Button 2 | Not used | Not used | +| Button 4 | Open commission window | The button is opening commissioning window to perform commissioning over BLE | + +### LEDs + +**Red** LED indicates current state of Thread network. It ables to be in +following states: + +| State | Description | +| :-------------------------- | :--------------------------------------------------------------------------- | +| Blinks with short pulses | Device is not commissioned to Thread, Thread is disabled | +| Blinls with frequent pulses | Device is commissioned, Thread enabled. Device trying to JOIN thread network | +| Blinks with whde pulses | Device commissioned and joined to thread network as CHILD | + +### CHIP tool commands + +1. Build + [chip-tool cli](https://github.com/project-chip/connectedhomeip/blob/master/examples/chip-tool/README.md) + +2. Pair with device + + ``` + ${CHIP_TOOL_DIR}/chip-tool pairing ble-thread ${NODE_ID} hex:${DATASET} ${PIN_CODE} ${DISCRIMINATOR} + ``` + + Example: + + ``` + ./chip-tool pairing ble-thread 1234 hex:0e080000000000010000000300000f35060004001fffe0020811111111222222220708fd61f77bd3df233e051000112233445566778899aabbccddeeff030e4f70656e54687265616444656d6f010212340410445f2b5ca6f2a93a55ce570a70efeecb0c0402a0fff8 20202021 3840 + ``` + +### OTA with Linux OTA Provider + +OTA feature enabled by default only for ota-requestor-app example. To enable OTA +feature for another Telink example: + +- set CONFIG_CHIP_OTA_REQUESTOR=y in corresponding "prj.conf" configuration + file. + +After build application with enabled OTA feature, use next binary files: + +- zephyr.bin - main binary to flash PCB (Use at least 2MB PCB). +- zephyr-ota.bin - binary for OTA Provider + +All binaries has the same SW version. To test OTA “zephyr-ota.bin” should have +higher SW version than base SW. Set CONFIG_CHIP_DEVICE_SOFTWARE_VERSION=2 in +corresponding “prj.conf” configuration file. + +Usage of OTA: + +- Build the [Linux OTA Provider](https://github.com/project-chip/connectedhomeip/blob/master/examples/ota-provider-app/linux) + + ``` + ./scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/ota-provider-app chip_config_network_layer_ble=false + ``` + +- Run the Linux OTA Provider with OTA image. + + ``` + ./chip-ota-provider-app -f zephyr-ota.bin + ``` + +- Provision the Linux OTA Provider using chip-tool + + ``` + ./chip-tool pairing onnetwork ${OTA_PROVIDER_NODE_ID} 20202021 + ``` + + here: + + - \${OTA_PROVIDER_NODE_ID} is the node id of Linux OTA Provider + +- Configure the ACL of the ota-provider-app to allow access + + ``` + ./chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": null}]' ${OTA_PROVIDER_NODE_ID} 0 + ``` + + here: + + - \${OTA_PROVIDER_NODE_ID} is the node id of Linux OTA Provider + +- Use the chip-tool to announce the ota-provider-app to start the OTA process + + ``` + ./chip-tool otasoftwareupdaterequestor announce-otaprovider ${OTA_PROVIDER_NODE_ID} 0 0 0 ${DEVICE_NODE_ID} 0 + ``` + + here: + + - \${OTA_PROVIDER_NODE_ID} is the node id of Linux OTA Provider + - \${DEVICE_NODE_ID} is the node id of paired device + +Once the transfer is complete, OTA requestor sends ApplyUpdateRequest command to +OTA provider for applying the image. Device will restart on successful +application of OTA image. diff --git a/_sources/examples/bridge-app/asr/README.md b/_sources/examples/bridge-app/asr/README.md new file mode 100644 index 000000000000..e686bdb9fff5 --- /dev/null +++ b/_sources/examples/bridge-app/asr/README.md @@ -0,0 +1,59 @@ +# Matter ASR Bridge Example + +This example demonstrates the Matter Bridge application on ASR platform. + +--- + +- [Matter ASR Bridge Example](#matter-asr-bridge-example) + - [Introduction](#introduction) + - [Building and Commissioning](#building-and-commissioning) + - [Testing the example](#testing-the-example) + +--- + +## Introduction + +A prototype application that demonstrates dynamic endpoint with device +commissioning and cluster control. It adds the non-chip device as endpoints on a +bridge(Matter device). In this example four light devices supporting on-off +cluster have been added as endpoints + +1. Light1 at endpoint 3 +2. Light2 at endpoint 4 +3. Light3 at endpoint 5 +4. Light4 at endpoint 6 + +## Building and Commissioning + +Please refer +[Building and Commissioning](../../../guides/asr_getting_started_guide.md#building-the-example-application) +guides to get started + +``` +./scripts/build/build_examples.py --target asr-$ASR_BOARD-bridge build +``` + +## Testing the example + +- An additional light-switch device is required to complete this example. +- Commission bridge device with node-id `1` +- Commission light-switch device with node-id `2` +- After bridge device and light-switch device successful commissioning, use + the GUI tool `DOGO` to input AT command `subdevice sync` for the bridge + device, and then use chip-tool to write ACL to the bridge device. + ``` + ./chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null },{"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": [2], "targets": null }]' 1 0 + ``` +- After successful commissioning, use the `chip-tool` for binding + light-switch's endpoint 1 with bridge device's endpoint 3 respectively. + ``` + ./chip-tool binding write binding '[{"fabricIndex": 1, "node":1, "endpoint":3, "cluster":6}]' 2 1 + ``` +- Light switch button + + This demo uses button to test changing the `Light1`, and the bridge device + will output log information: + + | Name | Pin | + | :----: | :---: | + | BUTTON | PAD12 | diff --git a/_sources/examples/bridge-app/esp32/README.md b/_sources/examples/bridge-app/esp32/README.md new file mode 100644 index 000000000000..64482346ceb5 --- /dev/null +++ b/_sources/examples/bridge-app/esp32/README.md @@ -0,0 +1,95 @@ +# Matter ESP32 Bridge App Example + +Please +[setup ESP-IDF and Matter Environment](../../../guides/esp32/setup_idf_chip.md) +and refer +[building and commissioning](../../../guides/esp32/build_app_and_commission.md) +guides to get started. + +--- + +- [Introduction](#introduction) +- [Dynamic Endpoints](#dynamic-endpoints) +- [Cluster control](#cluster-control) + +--- + +## Introduction + +A prototype application that demonstrates dynamic endpoint with device +commissioning and cluster control. It adds the non-chip device as endpoints on a +bridge(Matter device). In this example four light devices supporting on-off +cluster have been added as endpoints + +1. Light1 at endpoint 3 +2. Light2 at endpoint 7 +3. Light3 at endpoint 5 +4. Light4 at endpoint 6 + +## Dynamic Endpoints + +The Bridge Example makes use of Dynamic Endpoints. Current SDK support is +limited for dynamic endpoints, since endpoints are typically defined (along with +the clusters and attributes they contain) in a .zap file which then generates +code and static structures to define the endpoints. + +To support endpoints that are not statically defined, the ZCL attribute storage +mechanisms will hold additional endpoint information for `NUM_DYNAMIC_ENDPOINTS` +additional endpoints. These additional endpoint structures must be defined by +the application and can change at runtime. + +To facilitate the creation of these endpoint structures, several macros are +defined: + +`DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN(attrListName)` +`DECLARE_DYNAMIC_ATTRIBUTE(attId, attType, attSizeBytes, attrMask)` +`DECLARE_DYNAMIC_ATTRIBUTE_LIST_END(clusterRevision)` + +- These three macros are used to declare a list of attributes for use within a + cluster. The declaration must begin with the + `DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN` macro which will define the name of + the allocated attribute structure. Each attribute is then added by the + `DECLARE_DYNAMIC_ATTRIBUTE` macro. Finally, + `DECLARE_DYNAMIC_ATTRIBUTE_LIST_END` macro should be used to close the + definition. + +- All attributes defined with these macros will be configured as + `ATTRIBUTE_MASK_EXTERNAL_STORAGE` in the ZCL database and therefore will + rely on the application to maintain storage for the attribute. Consequently, + reads or writes to these attributes must be handled within the application + by the `emberAfExternalAttributeWriteCallback` and + `emberAfExternalAttributeReadCallback` functions. See the bridge + application's `main.cpp` for an example of this implementation. + +`DECLARE_DYNAMIC_CLUSTER_LIST_BEGIN(clusterListName)` +`DECLARE_DYNAMIC_CLUSTER(clusterId, clusterAttrs, role, incomingCommands, outgoingCommands)` +`DECLARE_DYNAMIC_CLUSTER_LIST_END` + +- These three macros are used to declare a list of clusters for use within a + endpoint. The declaration must begin with the + `DECLARE_DYNAMIC_CLUSTER_LIST_BEGIN` macro which will define the name of the + allocated cluster structure. Each cluster is then added by the + `DECLARE_DYNAMIC_CLUSTER` macro referencing attribute list previously + defined by the `DECLARE_DYNAMIC_ATTRIBUTE...` macros and the lists of + incoming/outgoing commands terminated by kInvalidCommandId (or nullptr if + there aren't any commands in the list). Finally, + `DECLARE_DYNAMIC_CLUSTER_LIST_END` macro should be used to close the + definition. + +`DECLARE_DYNAMIC_ENDPOINT(endpointName, clusterList)` + +- This macro is used to declare an endpoint and its associated cluster list, + which must be previously defined by the `DECLARE_DYNAMIC_CLUSTER...` macros. + +### Cluster control + +#### onoff + +To use the Client to send Matter commands, run the built executable and pass it +the target cluster name, the target command name as well as an endpoint id. + +``` +$ ./out/debug/chip-tool onoff on +``` + +The client will send a single command packet and then exit. diff --git a/_sources/examples/bridge-app/linux/README.md b/_sources/examples/bridge-app/linux/README.md new file mode 100644 index 000000000000..0e94a125c704 --- /dev/null +++ b/_sources/examples/bridge-app/linux/README.md @@ -0,0 +1,179 @@ +# Matter Linux Bridge Example + +An example demonstrating a simple lighting bridge and the use of dynamic +endpoints. The document will describe the theory of operation and how to build +and run Matter Linux Bridge Example on Raspberry Pi. This doc is tested on +**Ubuntu for Raspberry Pi Server 20.04 LTS (aarch64)** and **Ubuntu for +Raspberry Pi Desktop 20.10 (aarch64)** + +
    + +- [Matter Linux Bridge Example](#matter-linux-bridge-example) + - [Theory of Operation](#theory-of-operation) + - [Building](#building) + - [Running the Complete Example on Raspberry Pi 4](#running-the-complete-example-on-raspberry-pi-4) + +
    + +## Theory of Operation + +### Dynamic Endpoints + +The Bridge Example makes use of Dynamic Endpoints. Current SDK support is +limited for dynamic endpoints, since endpoints are typically defined (along with +the clusters and attributes they contain) in a .zap file which then generates +code and static structures to define the endpoints. + +To support endpoints that are not statically defined, the ZCL attribute storage +mechanisms will hold additional endpoint information for `NUM_DYNAMIC_ENDPOINTS` +additional endpoints. These additional endpoint structures must be defined by +the application and can change at runtime. + +To facilitate the creation of these endpoint structures, several macros are +defined: + +`DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN(attrListName)` +`DECLARE_DYNAMIC_ATTRIBUTE(attId, attType, attSizeBytes, attrMask)` +`DECLARE_DYNAMIC_ATTRIBUTE_LIST_END(clusterRevision)` + +- These three macros are used to declare a list of attributes for use within a + cluster. The declaration must begin with the + `DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN` macro which will define the name of + the allocated attribute structure. Each attribute is then added by the + `DECLARE_DYNAMIC_ATTRIBUTE` macro. Finally, + `DECLARE_DYNAMIC_ATTRIBUTE_LIST_END` macro should be used to close the + definition. + +- All attributes defined with these macros will be configured as + `ATTRIBUTE_MASK_EXTERNAL_STORAGE` in the ZCL database and therefore will + rely on the application to maintain storage for the attribute. Consequently, + reads or writes to these attributes must be handled within the application + by the `emberAfExternalAttributeWriteCallback` and + `emberAfExternalAttributeReadCallback` functions. See the bridge + application's `main.cpp` for an example of this implementation. + +`DECLARE_DYNAMIC_CLUSTER_LIST_BEGIN(clusterListName)` +`DECLARE_DYNAMIC_CLUSTER(clusterId, clusterAttrs, role, incomingCommands, outgoingCommands)` +`DECLARE_DYNAMIC_CLUSTER_LIST_END` + +- These three macros are used to declare a list of clusters for use within a + endpoint. The declaration must begin with the + `DECLARE_DYNAMIC_CLUSTER_LIST_BEGIN` macro which will define the name of the + allocated cluster structure. Each cluster is then added by the + `DECLARE_DYNAMIC_CLUSTER` macro referencing attribute list previously + defined by the `DECLARE_DYNAMIC_ATTRIBUTE...` macros and the lists of + incoming/outgoing commands terminated by kInvalidCommandId (or nullptr if + there aren't any commands in the list). Finally, + `DECLARE_DYNAMIC_CLUSTER_LIST_END` macro should be used to close the + definition. + +`DECLARE_DYNAMIC_ENDPOINT(endpointName, clusterList)` + +- This macro is used to declare an endpoint and its associated cluster list, + which must be previously defined by the `DECLARE_DYNAMIC_CLUSTER...` macros. + +### Limitations + +Because code generation is dependent upon the clusters and attributes defined in +the .zap file (for static endpoint generation), it is necessary to include a +defined endpoint within the .zap that contains _all_ the clusters that may be +used on dynamic endpoints. On the bridge example, this is done on endpoint 1, +which is used as a 'dummy' endpoint that will be disabled at runtime. Endpoint 0 +is also defined in the .zap and contains the bridge basic and configuration +clusters as well as the root descriptor cluster. + +### Bridge Implementation Example + +The example demonstrates the use of dynamic endpoints and the concept of adding +and removing endpoints at runtime. First, the example declares a +`bridgedLightEndpoint` data structure for a Light endpoint with `OnOff`, +`Descriptor`, `BridgedDeviceBasicInformation`, and `FixedLabel` clusters. + +Using this declared endpoint structure, three endpoints for three bridged lights +are dynamically added at endpoint ID's `2`, `3`, and `4`, representing +`Light 1`, `Light 2`, and `Light 3` respectively. + +Then, endpoint `3` is removed, simulating the deletion of `Light 2`. + +A fourth light, `Light 4`, is then added occupying endpoint ID `5`. + +Finally, `Light 2` is re-added, and will occupy endpoint ID `6`. + +All endpoints populate the `Bridged Device Basic Information` and `Fixed Label` +clusters. In the `Bridged Device Basic Information` cluster, the `reachable` +attribute is simulated. In the `Fixed Label` cluster, the `LabelList` attribute +is simulated with the value/label pair `"room"`/`[light name]`. + +## Building + +- Install tool chain + + ```sh + sudo apt-get install git gcc g++ python pkg-config libssl-dev libdbus-1-dev libglib2.0-dev ninja-build python3-venv python3-dev unzip + ``` + +- Build the example application: + + ```sh + cd ~/connectedhomeip/examples/bridge-app/linux + git submodule update --init + source third_party/connectedhomeip/scripts/activate.sh + gn gen out/debug + ninja -C out/debug + ``` + +- To delete generated executable, libraries and object files use: + + ```sh + cd ~/connectedhomeip/examples/bridge-app/linux + rm -rf out/ + ``` + +## Running the Complete Example on Raspberry Pi 4 + +- Prerequisites + + 1. A Raspberry Pi 4 board + 2. A USB Bluetooth Dongle, Ubuntu desktop will send Bluetooth advertisement, + which will block CHIP from connecting via BLE. On Ubuntu server, you need + to install `pi-bluetooth` via APT. + 3. Ubuntu 20.04 or newer image for ARM64 platform. + +- Building + + Follow [Building](#building) section of this document. + +- Running + + - [Optional] Plug USB Bluetooth dongle + + - Plug USB Bluetooth dongle and find its bluetooth device number. The + number after `hci` is the bluetooth device number, `1` in this + example. + + ```sh + $ hciconfig + hci1: Type: Primary Bus: USB + BD Address: 00:1A:7D:AA:BB:CC ACL MTU: 310:10 SCO MTU: 64:8 + UP RUNNING PSCAN ISCAN + RX bytes:20942 acl:1023 sco:0 events:1140 errors:0 + TX bytes:16559 acl:1011 sco:0 commands:121 errors:0 + + hci0: Type: Primary Bus: UART + BD Address: B8:27:EB:AA:BB:CC ACL MTU: 1021:8 SCO MTU: 64:1 + UP RUNNING PSCAN ISCAN + RX bytes:8609495 acl:14 sco:0 events:217484 errors:0 + TX bytes:92185 acl:20 sco:0 commands:5259 errors:0 + ``` + + - Run Linux Bridge Example App + + ```sh + cd ~/connectedhomeip/examples/bridge-app/linux + sudo out/debug/chip-bridge-app --ble-device [bluetooth device number] + # In this example, the device we want to use is hci1 + sudo out/debug/chip-bridge-app --ble-device 1 + ``` + + - Test the device using ChipDeviceController on your laptop / + workstation etc. diff --git a/_sources/examples/bridge-app/telink/README.md b/_sources/examples/bridge-app/telink/README.md new file mode 100644 index 000000000000..814c0d457ec9 --- /dev/null +++ b/_sources/examples/bridge-app/telink/README.md @@ -0,0 +1,326 @@ +# Matter Telink Bridge Example Application + +The Telink Bridge Example demonstrates a simple lighting bridge and the use of +dynamic endpoints. It uses buttons to test changing the lighting and device +states and LEDs to show the state of these changes. You can use this example as +a reference for creating your own application. + +Bridge together with its Bridged Devices is exposed as a single Node with a list +of endpoints. Consequently, a single Node ID and a single Operational +Certificate is assigned during Commissioning and a single pass through the +commissioning flow is required to bring the Bridge (along with its Bridged +Devices) onto a Fabric. This provides for a simple user experience, since the +user only needs to go through the commissioning flow for the Bridge, and not +separately for each of the Bridged Devices. + +![Telink B91 EVK](http://wiki.telink-semi.cn/wiki/assets/Hardware/B91_Generic_Starter_Kit_Hardware_Guide/connection_chart.png) + +## Introduction + +A prototype application that demonstrates dynamic endpoint with device +commissioning and cluster control. It adds the non-chip device as endpoints on a +bridge(Matter device). In this example four light devices supporting on-off +cluster and temperature sensor have been added as endpoints + +1. Light1 at endpoint 3 +2. Light2 at endpoint 7 +3. Light3 at endpoint 5 +4. Light4 at endpoint 6 +5. Temperature Sensor at endpoint 8 + +## Dynamic Endpoints + +The Bridge Example makes use of Dynamic Endpoints. Current SDK support is +limited for dynamic endpoints, since endpoints are typically defined (along with +the clusters and attributes they contain) in a .zap file which then generates +code and static structures to define the endpoints. + +To support endpoints that are not statically defined, the ZCL attribute storage +mechanisms will hold additional endpoint information for `NUM_DYNAMIC_ENDPOINTS` +additional endpoints. These additional endpoint structures must be defined by +the application and can change at runtime. + +To facilitate the creation of these endpoint structures, several macros are +defined: + +`DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN(attrListName)` +`DECLARE_DYNAMIC_ATTRIBUTE(attId, attType, attSizeBytes, attrMask)` +`DECLARE_DYNAMIC_ATTRIBUTE_LIST_END(clusterRevision)` + +- These three macros are used to declare a list of attributes for use within a + cluster. The declaration must begin with the + `DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN` macro which will define the name of + the allocated attribute structure. Each attribute is then added by the + `DECLARE_DYNAMIC_ATTRIBUTE` macro. Finally, + `DECLARE_DYNAMIC_ATTRIBUTE_LIST_END` macro should be used to close the + definition. + +- All attributes defined with these macros will be configured as + `ATTRIBUTE_MASK_EXTERNAL_STORAGE` in the ZCL database and therefore will + rely on the application to maintain storage for the attribute. Consequently, + reads or writes to these attributes must be handled within the application + by the `emberAfExternalAttributeWriteCallback` and + `emberAfExternalAttributeReadCallback` functions. See the bridge + application's `main.cpp` for an example of this implementation. + +`DECLARE_DYNAMIC_CLUSTER_LIST_BEGIN(clusterListName)` +`DECLARE_DYNAMIC_CLUSTER(clusterId, clusterAttrs, role, incomingCommands, outgoingCommands)` +`DECLARE_DYNAMIC_CLUSTER_LIST_END` + +- These three macros are used to declare a list of clusters for use within a + endpoint. The declaration must begin with the + `DECLARE_DYNAMIC_CLUSTER_LIST_BEGIN` macro which will define the name of the + allocated cluster structure. Each cluster is then added by the + `DECLARE_DYNAMIC_CLUSTER` macro referencing attribute list previously + defined by the `DECLARE_DYNAMIC_ATTRIBUTE...` macros and the lists of + incoming/outgoing commands terminated by kInvalidCommandId (or nullptr if + there aren't any commands in the list). Finally, + `DECLARE_DYNAMIC_CLUSTER_LIST_END` macro should be used to close the + definition. + +`DECLARE_DYNAMIC_ENDPOINT(endpointName, clusterList)` + +- This macro is used to declare an endpoint and its associated cluster list, + which must be previously defined by the `DECLARE_DYNAMIC_CLUSTER...` macros. + +## Build and flash + +1. Run the Docker container: + + ```bash + $ docker run -it --rm -v $PWD:/host -w /host ghcr.io/project-chip/chip-build-telink:$(wget -q -O - https://raw.githubusercontent.com/project-chip/connectedhomeip/master/.github/workflows/examples-telink.yaml 2> /dev/null | grep chip-build-telink | awk -F: '{print $NF}') + ``` + + Compatible docker image version can be found in next file: + + ```bash + $ .github/workflows/examples-telink.yaml + ``` + +2. Activate the build environment: + + ```bash + $ source ./scripts/activate.sh -p all,telink + ``` + +3. In the example dir run (replace __ with your board name, for + example, `tlsr9518adk80d`, `tlsr9528a` or `tlsr9258a`): + + ```bash + $ west build -b + ``` + + Also use key `-DFLASH_SIZE`, if your board has memory size different from 2 + MB, for example, `-DFLASH_SIZE=1m` or `-DFLASH_SIZE=4m`: + + ```bash + $ west build -b tlsr9518adk80d -- -DFLASH_SIZE=4m + ``` + +4. Flash binary: + + ``` + $ west flash --erase + ``` + +## Usage + +### UART + +To get output from device, connect UART to following pins: + +| Name | Pin | +| :--: | :---------------------------- | +| RX | PB3 (pin 17 of J34 connector) | +| TX | PB2 (pin 16 of J34 connector) | +| GND | GND | + +### Buttons + +The following buttons are available on **tlsr9518adk80d** board: + +| Name | Function | Description | +| :------- | :--------------------- | :----------------------------------------------------------------------------------------------------- | +| Button 1 | Factory reset | Perform factory reset to forget currently commissioned Thread network and back to uncommissioned state | +| Button 2 | Lighting control | Manually triggers the lighting state | +| Button 3 | Thread start | Commission thread with static credentials and enables the Thread on device | +| Button 4 | Open commission window | The button is opening commissioning window to perform commissioning over BLE | + +### LEDs + +#### Indicate current state of Thread network + +**Red** LED indicates current state of Thread network. It is able to be in +following states: + +| State | Description | +| :-------------------------- | :--------------------------------------------------------------------------- | +| Blinks with short pulses | Device is not commissioned to Thread, Thread is disabled | +| Blinks with frequent pulses | Device is commissioned, Thread enabled. Device trying to JOIN thread network | +| Blinks with wide pulses | Device commissioned and joined to thread network as CHILD | + +#### Indicate identify of device + +**Green** LED used to identify the device. The LED starts blinking when the +Identify command of the Identify cluster is received. The command's argument can +be used to specify the the effect. It is able to be in following effects: + +| Effect | Description | +| :------------------------------ | :--------------------------------------------------------------------------- | +| Blinks (200 ms on/200 ms off) | Blink (`Clusters::Identify::EffectIdentifierEnum::kBlink`) | +| Breathe (during 1000 ms) | Breathe (`Clusters::Identify::EffectIdentifierEnum::kBreathe`) | +| Blinks (50 ms on/950 ms off) | Okay (`Clusters::Identify::EffectIdentifierEnum::kOkay`) | +| Blinks (1000 ms on/1000 ms off) | Channel Change ( `Clusters::Identify::EffectIdentifierEnum::kChannelChange`) | +| Blinks (950 ms on/50 ms off) | Finish ( `Clusters::Identify::EffectIdentifierEnum::kFinishEffect`) | +| LED off | Stop (`Clusters::Identify::EffectIdentifierEnum::kStopEffect`) | + +### CHIP tool commands + +1. Build + [chip-tool cli](https://github.com/project-chip/connectedhomeip/blob/master/examples/chip-tool/README.md) + +2. Pair with device + + ``` + ${CHIP_TOOL_DIR}/chip-tool pairing ble-thread ${NODE_ID} hex:${DATASET} ${PIN_CODE} ${DISCRIMINATOR} + ``` + + Example: + + ``` + ./chip-tool pairing ble-thread 1234 hex:0e080000000000010000000300000f35060004001fffe0020811111111222222220708fd61f77bd3df233e051000112233445566778899aabbccddeeff030e4f70656e54687265616444656d6f010212340410445f2b5ca6f2a93a55ce570a70efeecb0c0402a0fff8 20202021 3840 + ``` + +3. Switch on the light: + + ``` + ${CHIP_TOOL_DIR}/chip-tool onoff on 1 2 + ``` + + here: + + - **onoff** is name of cluster + - **on** command to the cluster + - **1** ID of Node + - **2** ID of endpoint + +4. Switch off the light: + + ``` + ${CHIP_TOOL_DIR}/chip-tool onoff off 1 2 + ``` + + here: + + - **onoff** is name of cluster + - **off** command to the cluster + - **1** ID of Node + - **2** ID of endpoint + +5. Read the light state: + + ``` + ${CHIP_TOOL_DIR}/chip-tool onoff read on-off 1 2 + ``` + + here: + + - **onoff** is name of cluster + - **read** command to the cluster + - **on-off** attribute to read + - **1** ID of Node + - **2** ID of endpoint + +6. Change brightness of light: + + ``` + ${CHIP_TOOL_DIR}/chip-tool levelcontrol move-to-level 32 0 0 0 1 2 + ``` + + here: + + - **levelcontrol** is name of cluster + - **move-to-level** command to the cluster + - **32** brightness value + - **0** transition time + - **0** option mask + - **0** option override + - **1** ID of Node + - **2** ID of endpoint + +7. Read brightness level: + ``` + ./chip-tool levelcontrol read current-level 1 2 + ``` + here: + - **levelcontrol** is name of cluster + - **read** command to the cluster + - **current-level** attribute to read + - **1** ID of Node + - **2** ID of endpoint + +### OTA with Linux OTA Provider + +OTA feature enabled by default only for ota-requestor-app example. To enable OTA +feature for another Telink example: + +- set CONFIG_CHIP_OTA_REQUESTOR=y in corresponding "prj.conf" configuration + file. + +After build application with enabled OTA feature, use next binary files: + +- zephyr.bin - main binary to flash PCB (Use at least 2MB PCB). +- zephyr-ota.bin - binary for OTA Provider + +All binaries has the same SW version. To test OTA “zephyr-ota.bin” should have +higher SW version than base SW. Set CONFIG_CHIP_DEVICE_SOFTWARE_VERSION=2 in +corresponding “prj.conf” configuration file. + +Usage of OTA: + +- Build the [Linux OTA Provider](https://github.com/project-chip/connectedhomeip/blob/master/examples/ota-provider-app/linux) + + ``` + ./scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/ota-provider-app chip_config_network_layer_ble=false + ``` + +- Run the Linux OTA Provider with OTA image. + + ``` + ./chip-ota-provider-app -f zephyr-ota.bin + ``` + +- Provision the Linux OTA Provider using chip-tool + + ``` + ./chip-tool pairing onnetwork ${OTA_PROVIDER_NODE_ID} 20202021 + ``` + + here: + + - \${OTA_PROVIDER_NODE_ID} is the node id of Linux OTA Provider + +- Configure the ACL of the ota-provider-app to allow access + + ``` + ./chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": null}]' ${OTA_PROVIDER_NODE_ID} 0 + ``` + + here: + + - \${OTA_PROVIDER_NODE_ID} is the node id of Linux OTA Provider + +- Use the chip-tool to announce the ota-provider-app to start the OTA process + + ``` + ./chip-tool otasoftwareupdaterequestor announce-otaprovider ${OTA_PROVIDER_NODE_ID} 0 0 0 ${DEVICE_NODE_ID} 0 + ``` + + here: + + - \${OTA_PROVIDER_NODE_ID} is the node id of Linux OTA Provider + - \${DEVICE_NODE_ID} is the node id of paired device + +Once the transfer is complete, OTA requestor sends ApplyUpdateRequest command to +OTA provider for applying the image. Device will restart on successful +application of OTA image. diff --git a/_sources/examples/chef/NEW_CHEF_DEVICES.md b/_sources/examples/chef/NEW_CHEF_DEVICES.md new file mode 100644 index 000000000000..4d02b7ec56a2 --- /dev/null +++ b/_sources/examples/chef/NEW_CHEF_DEVICES.md @@ -0,0 +1,117 @@ +--- +orphan: true +--- + +# CHEF devices + +Device definitions reside in `examples/chef/devices` as .zap and .matter files. + +Generally you need to follow these steps to use a new device: + +- Create a zap/matter configuration (forking an existing one is the easiest) +- Rename to a final/stable name +- Test + +## Creating a new zap configuration + +The easiest way to get started is using an existing configuration. A template is +provided in `./examples/chef/devices/template.zap`. + +To open the zap GUI for this device, run: + +``` +./examples/chef/chef.py -g -d template +``` + +### Editing the zap configuration: + +Using the ZAP UI, make the following changes: + +- Leave Endpoint 0 unchanged +- Click the Edit/Pencil icon to change Endpoint 1 + (![Edit device type](../../../../../examples/chef/img/endpoint1_edit_pencil.png)) + - Update the device type to the new device and click "save" + (![edit device type](../../../../../examples/chef/img/endpoint_edit_type.png)) + - In the "Filter" section select "Enabled Clusters" and validate what + clusters are set + (![filter enabled clusters](../../../../../examples/chef/img/select_enabled_clusters.png)) + - Ensure clusters for the device type are enabled (this is generally + automatically the case) + - Click the gear icon on the cluster to further edit enabled + attributes and commands + - You can add additional optional clusters if needed (disable + filtering and use the search option) + +Once all edits are done, click "File" => "Save as..." to save it under a **NEW** +name inside `examples/chef/devices/`. + +NOTE: make sure you save under `examples/chef/devices` since internal paths +inside the saved file will be relative to the save location (it cannot simply be +moved later without manual editing). + +It is suggested to name this `rootnode_.zap` (e.g., +`rootnode_smokecoalarm.zap` for Matter Smoke CO Alarm device type) + +## Establishing a "final name" + +General naming convention for chef is `__` where `` is the +type of endpoint (and `` is almost always `rootnode`). + +The hash is a one-time uniquely generated identifier to allow separate +configurations for the same devices (e.g different features enabled). + +You can read more in `examples/chef/sample_app_util/README.md`, however the +short version is that you can determine a recommended name using: + +``` +./examples/chef/sample_app_util/sample_app_util.py zap --generate-name +``` + +and generally you want to just rename it via: + +``` +./examples/chef/sample_app_util/sample_app_util.py zap --rename-file +``` + +## Running code generation (to generate .matter file) + +To generate the matter file for your target, run + +``` +./scripts/tools/zap/generate.py +``` + +This should generate the corresponding `.matter` file for the zap file you +created. + +## Testing + +Basic device availability should show when running: + +``` +./examples/chef/chef.py -h | less +``` + +### Compilation + +This example uses `rootnode_contactsensor_27f76aeaf5` for commands. Substitute +your own device for testing newly created devices. + +``` +./examples/chef/chef.py \ + -t linux \ + -d rootnode_contactsensor_27f76aeaf5 \ + -b +``` + +Where options used are: + +- `-t` specifies the target platform +- `-d` specifies the device to build +- `-b` asks for build to be run + +### Execution + +Build will be available in +`examples/chef/linux/out/rootnode_contactsensor_27f76aeaf5` (path will vary +based on platform and device being built) diff --git a/_sources/examples/chef/README.md b/_sources/examples/chef/README.md new file mode 100644 index 000000000000..0998dfe7adf1 --- /dev/null +++ b/_sources/examples/chef/README.md @@ -0,0 +1,260 @@ +# MATTER CHEF APP + +The purpose of the chef app is to to: + +1. Increase the coverage of device types in Matter +2. Provide a sample application that may have its data model easily configured. + +Chef uses the shell app a starting point, but processes the data model defined +on ZAP files during build time. This procedure is handled by its unified build +script: `chef.py`. + +When processing ZAP files as part of the build process, Chef places the +auto-generated zap artifacts under its `out` temporary folder. Chef uses +artifacts from `zzz_generated` for CI/CD. + +All device types available (.zap files) are found inside the `devices` folder. + +## Building your first sample + +1. Make sure you have the toolchain installed for your desired target. +2. Run `chef.py` the first time to create a `config.yaml` configuration file. If + you already have SDK environment variables such as IDF_PATH (esp32) and + ZEPHYR_BASE (nrfconnect) it will use those values as default. +3. Update your the SDK paths on `config.yaml`. TTY is the path used by the + platform to enumerate its device as a serial port. Typical values are: + +``` + # ESP32 macOS + + TTY: /dev/tty.usbmodemXXXXXXX + + # ESP32 Linux + + TTY: /dev/ttyACM0 + + # NRFCONNECT macOS + + TTY: /dev/tty.usbserial-XXXXX + + # NRFCONNECT Linux + + TTY: /dev/ttyUSB0 +``` + +4. Run `$ chef.py -u` to update zap and the toolchain (on selected platforms). +5. Run `$ chef.py -gzbf -t -d lighting`. This command will run the + ZAP GUI opening the `devices/lighting.zap` file and will allow editing. It + will then generate the zap artifacts, place them on the `zap-generated` + folder, run a build and flash the binary in your target. +6. Run `chef.py -h` to see all available commands. + +## Creating a new device type in your device library + +Follow guide in [NEW_CHEF_DEVICES.md](NEW_CHEF_DEVICES.md). + +## Folder Structure and Guidelines + +- ``: build system and `main.cpp` file for every supported platform. + When porting a new platform, please minimize the source code in this folder, + favoring the `common` folder for code that is not platform related. +- `common`: contains code shared between different platforms. It may contain + source code that enables specific features such as `LightingManager` class + or `LockManager`, as long as the application dynamically identify the + presence of the relevant cluster configurations and it doesn't break the use + cases where chef is built without these clusters. +- `devices`: contains the data models that may be used with chef. As of Matter + 1.0 the data models are defined using .zap files. +- `out`: temporary folder used for placing ZAP generated artifacts. +- `sample_app_util`: guidelines and scripts for generating file names for new + device types committed to the `devices` folder. +- `config.yaml`: contains general configuration for the `chef.py` script. As + of Matter 1.0 this is used exclusively for toolchain and TTY interface + paths. +- `chef.py`: main script for generating samples. More info on its help + `chef.py -h`. + +## General Linux Options + +When building chef for the Linux platform there are several options available at +runtime. These options are also available for many Linux samples. Do not +conflate these with chef options available at build time. + +Ex.: + +- --discriminator : A 12-bit unsigned integer match the value + which a device advertises during commissioning. +- --passcode : A 27-bit unsigned integer, which serves as proof of + possession during commissioning. If not provided to compute a verifier, the + --spake2p-verifier-base64 must be provided. +- --secured-device-port : A 16-bit unsigned integer specifying the + listen port to use for secure device messages (default is 5540). +- --KVS : A file to store Key Value Store items. + +For a full list, call the generated linux binary with + +- -h, --help: Print this output and then exit. + +## CI + +All CI jobs for chef can be found in `.github/workflows/chef.yaml`. + +These jobs use a platform-specific image with base `chip-build`. Such images +contain the toolchain for the respective platform under `/opt`. + +CI jobs call chef with the options `--ci -t $PLATFORM`. The `--ci` option will +execute builds for all devices specified in `ci_allow_list` defined in +`cicd_config.json` (so long as these devices are also in `/devices`) on the +specified platform. + +CI jobs also call the function `bundle_$PLATFORM` at the end of each example +build. This function should copy or move build output files from the build +output location into `_CD_STAGING_DIR`. Typically, the set of files touched is +the minimal set of files needed to flash a device. See the function +`bundle_esp32` for reference. + +### Adding a platform + +First, implement a `bundle_$PLATFORM` function. + +Next, ensure that the examples in `ci_allow_list` build in a container using the +relevant platform image. You can simulate the workflow locally by mounting your +CHIP repo into a container and executing the CI command: + +```shell +docker run -it --mount source=$(pwd),target=/workspace,type=bind ghcr.io/project-chip/chip-build-$PLATFORM:$VERSION +``` + +In the container: + +```shell +chown -R $(whoami) /workspace +cd /workspace +source ./scripts/bootstrap.sh +source ./scripts/activate.sh +./examples/chef/chef.py --ci -t $PLATFORM +``` + +Once you are confident the CI examples build and bundle in a container, add a +new job to the chef workflow. + +Replace all instances of `$PLATFORM` with the new platform. Replace `$VERSION` +with the image version used in the rest of the workflows, or update the image +version for all images in the workflow as needed. + +```yaml +chef_$PLATFORM: + name: Chef - $PLATFORM CI Examples + runs-on: ubuntu-latest + if: github.actor != 'restyled-io[bot]' + + container: + image: ghcr.io/project-chip/chip-build-$PLATFORM:$VERSION + options: --user root + + steps: + - name: Checkout + uses: actions/checkout@v3 + - name: Checkout submodules & Bootstrap + uses: ./.github/actions/checkout-submodules-and-bootstrap + with: + platform: $PLATFORM + - name: CI Examples $PLATFORM + shell: bash + run: | + ./scripts/run_in_build_env.sh "./examples/chef/chef.py --ci -t $PLATFORM" +``` + +## CD + +Once CI is enabled for a platform, the platform may also be integrated into +`integrations/cloudbuild/`, where chef builds are defined in `chef.yaml`. See +the `README` in this path for more information. + +Note that the image used in `chef.yaml` is `chip-build-vscode`. See +`docker/images/chip-build-vscode/Dockerfile` for the source of this image. This +image is a combination of the individual toolchain images. Therefore, before a +platform is integrated into chef CD, the toolchain should be copied into +`chip-build-vscode` and `chef.yaml` should be updated to use the new image +version. + +Finally, add the new platform to `cd_platforms` in `cicd_config.json`. The +configuration should follow the following schema: + +```json +"$PLATFORM": { + "output_archive_prefix_1": ["option_1", "option_2"], + "output_archive_prefix_2": [], +} +``` + +Take note of the configuration for `linux`: + +```json +"linux": { + "linux_x86": ["--cpu_type", "x64"], + "linux_arm64_ipv6only": ["--cpu_type", "arm64", "--ipv6only"] +}, +``` + +This will produce output archives prefixed `linux_x86` and +`linux_arm_64_ipv6only` and will append the respective options to each build +command for these targets. + +To test your configuration locally, you may employ a similar strategy as in CI: + +```shell +docker run -it --mount source=$(pwd),target=/workspace,type=bind ghcr.io/project-chip/chip-build-vscode:$VERSION +``` + +In the container: + +```shell +chown -R $(whoami) /workspace +cd /workspace +source ./scripts/bootstrap.sh +source ./scripts/activate.sh +./examples/chef/chef.py --build_all --keep_going +``` + +You may also use the Google Cloud Build local builder as detailed in the +`README` of `integrations/cloudbuild/`. + +## Adding new devices + +To add new devices for chef: + +- Execute `python sample_app_util.py zap --rename-file` to rename + the example and place the new file in `examples/chef/devices`. + - See the `README` in `examples/chef/sample_app_util/` for more info. +- Execute `scripts/tools/zap_regen_all.py`, commit `zzz_generated` and + `examples/chef/devices`. + - This is gated by the workflow in `.github/workflows/zap_templates.yaml`. +- All devices added to the repository are built in CD. + +## Manufacturer Extensions / Custom Clusters + +You may add vendor-defined features to chef. The +`rootnode_onofflight_meisample*` device showcases its usage by using the Sample +MEI cluster which is defined on +`src/app/zap-templates/zcl/data-model/chip/sample-mei-cluster.xml` + +This cluster has + +- One boolean attribute: `flip-flop` +- A `ping` command with no arguments +- A command/response pair `add-arguments`. The command takes two uint8 + arguments and the response command returns their sum. + +You may test the `Sample MEI` via chip-tool using the following commands: + +``` +# commissioning of on-network chef device +chip-tool pairing onnetwork 1 20202021 +# tests command to sum arguments: returns 30 +chip-tool samplemei add-arguments 1 1 10 20 +# sets Flip-Flop to false +chip-tool samplemei write flip-flop 0 1 1 +# reads Flip-Flop +chip-tool samplemei read flip-flop 1 1 +``` diff --git a/_sources/examples/chef/README_DEVICE.md b/_sources/examples/chef/README_DEVICE.md new file mode 100644 index 000000000000..cc3a764ee8f0 --- /dev/null +++ b/_sources/examples/chef/README_DEVICE.md @@ -0,0 +1,85 @@ +# Matter Shell - Device Layer module + +The chip::DeviceLayer APIs may be invoked via the Matter Shell CLI. + +## Command List + +- [help](#help) +- [config](#config) +- [get](#get-parameter) +- [start](#start) + +## Command Details + +### help + +List the Device CLI commands. + +```bash +> device help + help Usage: device + start Start the device layer. Usage: device start + get Get configuration value. Usage: device get + config Dump entire configuration of device. Usage: device dump +Done +``` + +### config + +Dump the configuration of the device. + +```bash +> device config +VendorId: 235a +ProductId: feff +HardwareVersion: 0001 +SerialNumber: +ServiceId: +FabricId: +PinCode: +Discriminator: +DeviceId: +DeviceCert: +DeviceCaCerts: +MfrDeviceId: +MfrDeviceCert: +MfgDeviceCaCerts: +``` + +### get \ + +- parameter: name of field to query + +Where valid parameter names include: + +- vendorid: Vendor Identifier +- productid: Product Identifier +- hardwarever: Hardware Version +- serial: Serial Number +- deviceid: Device Identification Number +- cert: Device Certificate +- cacerts: Device CA Certificates +- mfrdeviceid: Manufacturer Device Identification Number +- mfrcert: Manufacturer Device Certificate +- mfrcacerts: Manufacturer Device CA Certs +- pincode: Setup Pin Code +- discriminator: Setup Discriminator +- serviceid: Service Identifier +- fabricid: Fabric Identifier + +```bash +> device get vendorid +235a +Done +``` + +### start + +Initialize the Matter stack and start the device layer event loop. + +```bash +> device start +Init CHIP Stack +Starting Platform Manager Event Loop +Done +``` diff --git a/_sources/examples/chef/README_OTCLI.md b/_sources/examples/chef/README_OTCLI.md new file mode 100644 index 000000000000..d9cfc9db1573 --- /dev/null +++ b/_sources/examples/chef/README_OTCLI.md @@ -0,0 +1,50 @@ +# Matter Shell - OpenThread CLI pass-through + +The Matter Shell CLI can execute pass-through commands to the +[OpenThread CLI](https://github.com/openthread/openthread/blob/master/src/cli/README.md) +directly. + +## Setup + +### Embedded + +On embedded platforms, the otcli commands are available simply when OpenThread +support is enabled. + +### Linux + +On embedded Linux platforms, otcli commands require installation of some +OpenThread daemons: + +``` +# Start Border Router agent +sudo /usr/local/sbin/otbr-agent -d6 -v -I wpan0 spinel+hdlc+forkpty:///usr/local/bin/ot-rcp\?forkpty-arg=5 +``` + +If this command is not available, the follow instructions will build and install +it: + +``` +# Build OpenThread Interface (simulation used as example -- alternatively could be RCP hardware) +cd third_party/openthread/repo +./script/bootstrap +mkdir build && cd build +cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local -DOT_PLATFORM=simulation -GNinja +ninja -j8 && sudo ninja install + +# Build Border Router functionality +cd third_party/ot-br-posix/repo +./script/bootstrap +mkdir build && cd build +cmake .. -DOTBR_DBUS=ON -GNinja -DCMAKE_INSTALL_PREFIX=/usr/local - +ninja -j8 && sudo ninja install + +# Start Border Router agent +sudo /usr/local/sbin/otbr-agent -d6 -v -I wpan0 spinel+hdlc+forkpty:///usr/local/bin/ot-rcp\?forkpty-arg=5 + +# In a new shell, at top-level of CHIP repo, test Thread device layer is operational +git submodule update --init +source scripts/activate.sh +gn gen out/default +ninja -C out/default src/platform/tests:TestThreadStackMgr_run +``` diff --git a/_sources/examples/chef/README_SHELL.md b/_sources/examples/chef/README_SHELL.md new file mode 100644 index 000000000000..793de37cc03f --- /dev/null +++ b/_sources/examples/chef/README_SHELL.md @@ -0,0 +1,120 @@ +# Matter Shell Reference + +The `chip-shell` firmware exposes configuration and management APIs via a +command line interface (CLI). Use the shell CLI to experiment with Matter +interactively, which can also be used with additional application code. The +Matter functional test scripts use the shell CLI to execute test cases. + +## Separator and escaping characters + +The whitespace character (`' '`) is used to delimit the command name and the +different arguments, together with tab (`'\t'`) and new line characters (`'\r'`, +`'\n'`). + +Some arguments might require to accept whitespaces on them. For those cases the +backslash character (`'\'`) can be used to escape separators or the backslash +itself. + +Example: + +```bash +> networkname Test\ Network +Done +> networkname +Test Network +Done +> +``` + +## Matter Shell Command List + +- [base64](#base64-decode-b64_string) +- [device](https://github.com/project-chip/connectedhomeip/blob/master/README_DEVICE.md) +- [echo](#echo-string) +- [exit](#exit) +- [help](#help) +- [otcli](https://github.com/project-chip/connectedhomeip/blob/master/README_OTCLI.md) +- [rand](#rand) +- server +- [version](#version) + +## Matter Shell Command Details + +### help + +Display a list of all top-level commands supported and a brief description. + +```bash +> help + echo Echo back provided inputs + log Logging utilities + rand Random number utilities + base64 Base64 encode / decode utilities + device Device Layer commands + otcli Dispatch OpenThread CLI command + ping Using Echo Protocol to measure packet loss across network paths + exit Exit the shell application + help List out all top level commands + version Output the software version +Done +``` + +### base64 decode \ + +Decode the given base64 string into hex. + +```bash +> base64 decode EjQ= +1234 +Done +``` + +### base64 encode \ + +Decode the given hex string into base64. + +```bash +> base64 encode 1234 +EjQ= +Done +``` + +### echo \ + +Echo back the provided string to the terminal. + +```bash +> echo hello +hello +Done +``` + +### exit + +Exit the shell terminal. On an embedded system this may trigger a watchdog +reset. + +```bash +> exit +Goodbye +``` + +### rand + +Output a single byte random number. + +```bash +> rand +103 +Done +``` + +### version + +Output the version of the Matter stack. + +```bash +> version +CHIP 0.0.g54591338-dirty +Done +``` diff --git a/_sources/examples/chef/nrfconnect/README.md b/_sources/examples/chef/nrfconnect/README.md new file mode 100644 index 000000000000..2a0170ae08e6 --- /dev/null +++ b/_sources/examples/chef/nrfconnect/README.md @@ -0,0 +1,11 @@ +# CHIP nRF Connect SDK Shell Application + +A [chip-shell](https://github.com/project-chip/connectedhomeip/blob/master/README.md) project for the Nordic nRF52840 and nRF5340 +development kits, built using the nRF Connect SDK. + +## Building + +The steps to build the Shell Application for Nordic Semiconductor's development +kits are exactly the same as in case of the Lock Example. Please refer to +[this guide](../../lock-app/nrfconnect/README.md) to learn how to build, +program, and debug the application. diff --git a/_sources/examples/chef/sample_app_util/README.md b/_sources/examples/chef/sample_app_util/README.md new file mode 100644 index 000000000000..1ad03349303e --- /dev/null +++ b/_sources/examples/chef/sample_app_util/README.md @@ -0,0 +1,181 @@ +# Chef Build Conventions + +## Overview + +It is convenient to follow some naming and build conventions for Chef tool due +to the large volume of sample apps that may be created and the ambiguity that +may result from arbitrary names. + +There are three components to the convention proposed here: + +1. The naming convention for the sample matter device and clusters (referred to + here as the `sample app`). +2. The naming convention to use for the build files which will be flashed on the + devices. +3. The usage of metadata files that shall accompany build files to provide more + detailed information about builds. + +The convention proposed here should be adopted by the zap files provided in +`examples/chef/devices` and the builds generated from Chef tool in CI. + +## Limitations + +The largest filename that can be used on MacOS and Linux is 255 characters. If a +sample app name would exceed this limit by following this convention, then the +sample app should be given an arbitrary name. + +This limitation is called out, but, with the given naming conventions, this +should rarely happen. + +## Convention + +### Sample App Naming Convention + +Sample apps should be named by concatenating the name of all endpoints in the +order of their index. Endpoint names are separated by underscores (`_`) and a 10 +character hash[^hash_note] which is randomly generated. + +The naming convention tool should be used for every newly created app. The name +should only need to be updated if the endpoints of the app are changed. + +Valid sample app names conform to the following format: + +``` +__ +``` + +For example, here are some valid names: + +``` +rootnode_extendedcolorlight_H1l9gnQDYl +rootnode_speaker_8qRQaEj0Hy +rootnode_lightsensor_L6dEbmVDah +rootnode_dimmablelight_rWsDiwzw2t +rootnode_pressuresensor_03quf7tPOL +rootnode_flowsensor_ixbAboycie +rootnode_windowcovering_b9QoiScjOq +rootnode_doorlock_d5wtU7sjFR +rootnode_thermostat_KuQYArmwl7 +rootnode_dimmablelight_7pNE3GVarn +rootnode_temperaturesensor_i0wGnDVUAc +rootnode_occupancysensor_wyGeQSokNp +rootnode_humiditysensor_pv0comNKyT +bridgednode_temperaturesensor_onofflight_onoffpluginunit_MI9DSdkH8H +``` + +[^hash_note]: + + The 10 character hash used to be generated by consuming the JSON encoded + metadata. This is no longer the case. It was found that the hash encoding + only served to differentiate one app from another (the initial goal) and + there was little value in tying the generated hash to the config data + because there wasn't a use case for decoding it as long as the config file + was packaged with the generated app. + +### Sample App Build Naming Convention + +The sample app builds formats will be named by pre-pending the zap file name +(described above) with the platform and appending connectivity info. + +Valid build names conform to the following format: + +``` +_ +``` + +Note that `` follows the convention: +`__`. + +Together that is: + +``` +___ +``` + +The list of platforms supported here (as of writing this) are: + +``` +m5stack +brd4161a +nrf52840dk +linux_x86 +``` + +For example, here are some valid names: + +``` +m5stack_rootnode_humiditysensor_pv0comNKyT +brd4161a_rootnode_humiditysensor_pv0comNKyT +nrf52840dk_rootnode_humiditysensor_pv0comNKyT +linux_x86_rootnode_humiditysensor_pv0comNKyT +``` + +### Metadata file convention + +Metadata files are `yaml` files that should accompany build files. + +The metadata files have a structure as follows: + +``` +- : + client_clusters: + : + attributes: + : + ... + commands: + - + - ... + server_clusters: + : + attributes: + : + ... + commands: + - + - ... +- : ... +``` + +For an example, see +[sample_zap_file_meta.yaml](https://github.com/project-chip/connectedhomeip/blob/master/examples/chef/sample_app_util/test_files/sample_zap_file_meta.yaml) which was +generated from [sample_zap_file.zap](https://github.com/project-chip/connectedhomeip/blob/master/examples/chef/sample_app_util/test_files/sample_zap_file.zap). + +The following conventions are used: + +- All lists are sorted alphabetically. +- If a list contains dictionaries, it will be sorted by the "name" key. If it + does not contain "name" key, it will be sorted by the first key common to + all dictionaries that comes first alphabetically. +- The list of endpoints is excluded from the above conventions. Endpoints are + ordered according to their endpoint number; here, the endpoint number is the + same as the order they are read from the zap file. + +As an example, take a look at +[sample_zap_file.yaml](https://github.com/project-chip/connectedhomeip/blob/master/examples/chef/sample_app_util/test_files/sample_zap_file.yaml) + +## Utility Usage + +There are a few primary usage cases for the utility +[sample_app_util.py](https://github.com/project-chip/connectedhomeip/blob/master/sample_app_util.py). Details are provided by using +`python sample_app_util.py zap --help`. Below is a summary. + +| Command | Description | +| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `python sample_app_util.py zap --generate-name` | Generates the name for a zap file per the specified convention | +| `python sample_app_util.py zap --rename-file` | Renames the zap file per specified convention | +| `python sample_app_util.py zap --generate-metadata [output_path]` | Generates the metadata file adjacent to the zap file with `.yaml` extension. If `[output_path]` is provided then the metadata file will be stored at the location specified. | + +## Running Tests + +Navigate to the base directory of this README. + +``` +cd /examples/chef/sample_app_util +``` + +Run unit tests. + +``` +python -m unittest +``` diff --git a/_sources/examples/chip-tool/README.md b/_sources/examples/chip-tool/README.md new file mode 100644 index 000000000000..19fbd2a7b58d --- /dev/null +++ b/_sources/examples/chip-tool/README.md @@ -0,0 +1,637 @@ +# Matter Client Example + +An example application that uses Matter to send messages to a Matter server. + +--- + +- [Building the Example Application](#building-the-example-application) +- [Using the Client to Commission a Device](#using-the-client-to-commission-a-device) + +--- + +## Building the Example Application + +See [the build guide](../../guides/BUILDING.md#prerequisites) for general +background on build prerequisites. + +Building the example application is quite straightforward. It can either be done +as part of an overall "build everything" build: + +``` +./gn_build.sh +``` + +which puts the binary at `out/debug/standalone/chip-tool` or directly via: + +``` +scripts/examples/gn_build_example.sh examples/chip-tool SOME-PATH/ +``` + +which puts the binary at `SOME-PATH/chip-tool`. + +### Using message tracing + +Message tracing allows capture of the secure messages which can be used for test +automation. + +There are additional flags to chip-tool to control where the traces should go: + +- --trace_file Outputs trace data to the specified file. +- --trace_log <0/1> Outputs trace data to the console with automation logs if + set to 1 + +For example: + +``` +out/with_trace/chip-tool pairing --trace_file trace.log +``` + +## Using the Client to commission a device + +In order to send commands to a device, it must be commissioned with the client. +chip-tool currently only supports commissioning and remembering one device at a +time. The configuration state is stored in `/tmp/chip_tool_config.ini`; deleting +this and other `.ini` files in `/tmp` can sometimes resolve issues due to stale +configuration. + +#### Commission a device + +To initiate a client commissioning request to a device, run the built executable +and choose the pairing mode. + +#### Commission a device over BLE + +Run the built executable and pass it the discriminator and pairing code of the +remote device, as well as the network credentials to use. + +The command below uses the default values hard-coded into the debug versions of +the ESP32 all-clusters-app to commission it onto a Wi-Fi network: + +``` +chip-tool pairing ble-wifi ${NODE_ID_TO_ASSIGN} ${SSID} ${PASSWORD} 20202021 3840 +``` + +where: + +- \${NODE_ID_TO_ASSIGN} (which must be a decimal number or a `0x`-prefixed hex + number) is the node id to assign to the node being commissioned. +- \${SSID} is the Wi-Fi SSID either as a string, or in the form `hex:XXXXXXXX` + where the bytes of the SSID are encoded as two-digit hex numbers. +- \${PASSWORD} is the Wi-Fi password, again either as a string or as hex data + +For example: + +``` +chip-tool pairing ble-wifi 0x11 xyz secret 20202021 3840 +``` + +or equivalently: + +``` +chip-tool pairing ble-wifi 17 hex:787980 hex:736563726574 20202021 3840 +``` + +#### Pair a device over IP + +The command below will discover devices and try to pair with the first one it +discovers using the provided setup code. + +``` +chip-tool pairing onnetwork ${NODE_ID_TO_ASSIGN} 20202021 +``` + +The command below will discover devices with long discriminator 3840 and try to +pair with the first one it discovers using the provided setup code. + +``` +chip-tool pairing onnetwork-long ${NODE_ID_TO_ASSIGN} 20202021 3840 +``` + +The command below will discover devices based on the given QR code (which +devices log when they start up) and try to pair with the first one it discovers. + +``` +chip-tool pairing code ${NODE_ID_TO_ASSIGN} MT:####### +``` + +In all these cases, the device will be assigned node id `${NODE_ID_TO_ASSIGN}` +(which must be a decimal number or a 0x-prefixed hex number). + +#### Trust Store + +Trust store will be automatically created using the default Test Attestation +PAA. To use a different set of PAAs, pass the path using the optional parameter +--paa-trust-store-path while running the built executable. Trusted PAAs are +available at credentials/development/paa-root-certs/. + +The command below will select a set of trusted PAAs to be used during +Attestation Verification. It will also discover devices with long discriminator +3840 and try to pair with the first one it discovers using the provided setup +code. + +``` +chip-tool pairing onnetwork-long ${NODE_ID_TO_ASSIGN} 20202021 3840 --paa-trust-store-path path/to/PAAs +``` + +### Forget the currently-commissioned device + +``` +chip-tool pairing unpair +``` + +## Using the Client to Send Matter Commands + +To use the Client to send Matter commands, run the built executable and pass it +the target cluster name, the target command name as well as an endpoint id. + +The endpoint id must be between 1 and 240. + +``` +chip-tool onoff on 1 +``` + +The client will send a single command packet and then exit. + +## Configuring the server side for Group Commands + +1. Commission and pair device with nodeId 1234 + +2. Add group Keyset to device + +``` +chip-tool groupkeymanagement key-set-write GroupKeySet node-id endpoint-id +chip-tool groupkeymanagement key-set-write '{"groupKeySetID": 42, \ + "groupKeySecurityPolicy": 0, "epochKey0": \ + "d0d1d2d3d4d5d6d7d8d9dadbdcdddedf", "epochStartTime0": 2220000,"epochKey1": \ + "d1d1d2d3d4d5d6d7d8d9dadbdcdddedf", "epochStartTime1": 2220001,"epochKey2": \ + "d2d1d2d3d4d5d6d7d8d9dadbdcdddedf", "epochStartTime2": 2220002 }' 1234 0 +``` + +3. Bind Key to group + +``` +chip-tool groupkeymanagement write group-key-map attr-value node-id endpoint-id +chip-tool groupkeymanagement write group-key-map '[{"groupId": 16705, "groupKeySetID": 42}]' 1234 0 +``` + +4. Add Group to device + +``` +chip-tool groups add-group GroupId GroupName node-id endpoint-id +chip-tool groups add-group 0x4141 Light 1234 1 +``` + +## Configuring the client for Group Commands + +Prior to sending a Group command, both the end device and the Client (Chip-tool) +must be configured appropriately. + +To configure the client please use the groupsettings option + +``` +chip-tool groupsettings +``` + +A group with a valid encryption key needs to be set. The groupid and the +encryption key must match the one configured on the end device. + +To add a group + +``` +chip-tool groupsettings add-group groupName groupId +chip-tool groupsettings add-group TestName 0x4141 +``` + +To add a keyset + +``` +chip-tool groupsettings add-keysets keysetId keyPolicy validityTime EpochKey +chip-tool groupsettings add-keysets 0xAAAA 0 0x000000000021dfe0 hex:d0d1d2d3d4d5d6d7d8d9dadbdcdddedf +``` + +Take note that the epoch key must be in hex form with the 'hex:' prefix + +Finally to bind the keyset to the group + +``` +chip-tool groupsettings bind-keyset groupId keysetId +chip-tool groupsettings bind-keyset 0x4141 0xAAAA +``` + +## Using the Client to Send Group (Multicast) Matter Commands + +To use the Client to send Matter commands, run the built executable and pass it +the target cluster name, the target command name, the Group Id in Node Id form +(`0xffffffffffffXXXX`) and an used endpoint Id. Take note that Only commands and +attributes write can be send with Group Id. Also note that a group ACL needs to +be installed before a command sent to the group will be accepted. See +[the access control guide](../../guides/access-control-guide.md#installing-a-group-acl) + +E.G. sending to group Id 0x4141 + +``` +chip-tool onoff on 0xffffffffffff4141 1 +``` + +The client will send a single multicast command packet and then exit. + +### How to get the list of supported clusters + +To get the list of supported clusters, run the built executable without any +arguments. + +``` +chip-tool +``` + +Example output: + +```bash +Usage: + ./chip-tool cluster_name command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Clusters: | + +-------------------------------------------------------------------------------------+ + | * barriercontrol | + | * basic | + | * colorcontrol | + | * doorlock | + | * groups | + | * iaszone | + | * identify | + | * levelcontrol | + | * onoff | + | * pairing | + | * payload | + | * scenes | + | * temperaturemeasurement | + +-------------------------------------------------------------------------------------+ +``` + +### How to get the list of supported commands for a specific cluster + +To get the list of commands for a specific cluster, run the built executable +with the target cluster name. + +``` +chip-tool onoff +``` + +### How to get the list of supported attributes for a specific cluster + +To the the list of attributes for a specific cluster, run the built executable +with the target cluster name and the `read` command name. + +``` +chip-tool onoff read +``` + +### How to get the list of parameters for a command + +To get the list of parameters for a specific command, run the built executable +with the target cluster name and the target command name + +``` +chip-tool onoff on +``` + +### Run a test suite against a paired peer device + +``` +chip-tool tests Test_TC_OO_1_1 +``` + +## Using the Client for Setup Payload + +### How to parse a setup code + +To parse a setup code, run the built executable with the `payload` cluster name +and the `parse-setup-payload` command + +``` +chip-tool payload parse-setup-payload code +``` + +#### QR Code + +``` +chip-tool payload parse-setup-payload "MT:#####" +``` + +#### QR Code with optional Vendor Info + +``` +chip-tool payload parse-setup-payload "MT:#####" +``` + +#### Manual Setup Code + +``` +chip-tool payload parse-setup-payload "#####" +``` + +# Using the Client for Additional Data Payload + +To parse an additional data payload, run the built executable with the `payload` +cluster name and the `parse-additional-data-payload` command + +``` +chip-tool payload parse-additional-data-payload "#####" +``` + +# Command Reference + +## Command List + +- [barriercontrol](#barriercontrol) +- [basic](#basic) +- [colorcontrol](#colorcontrol) +- [doorlock](#doorlock) +- [groups](#groups) +- [iaszone](#iaszone) +- [identify](#identify) +- [levelcontrol](#levelcontrol) +- [onoff](#onoff) +- [pairing](#pairing) +- [payload](#payload) +- [scenes](#scenes) +- [temperaturemeasurement](#temperaturemeasurement) + +## Command Details + +### barriercontrol + +```bash +Usage: + ./chip-tool barriercontrol command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Commands: | + +-------------------------------------------------------------------------------------+ + | * barrier-control-go-to-percent | + | * barrier-control-stop | + | * discover | + | * read | + +-------------------------------------------------------------------------------------+ +``` + +### basic + +```bash +Usage: + ./chip-tool basic command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Commands: | + +-------------------------------------------------------------------------------------+ + | * reset-to-factory-defaults | + | * ping | + | * discover | + | * read | + +-------------------------------------------------------------------------------------+ +``` + +### colorcontrol + +```bash +Usage: + ./chip-tool colorcontrol command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Commands: | + +-------------------------------------------------------------------------------------+ + | * move-color | + | * move-color-temperature | + | * move-hue | + | * move-saturation | + | * move-to-color | + | * move-to-color-temperature | + | * move-to-hue | + | * move-to-hue-and-saturation | + | * move-to-saturation | + | * step-color | + | * step-color-temperature | + | * step-hue | + | * step-saturation | + | * stop-move-step | + | * discover | + | * read | + | * report | + +-------------------------------------------------------------------------------------+ +``` + +### doorlock + +```bash +Usage: + ./chip-tool doorlock command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Commands: | + +-------------------------------------------------------------------------------------+ + | * clear-all-pins | + | * clear-all-rfids | + | * clear-holiday-schedule | + | * clear-pin | + | * clear-rfid | + | * clear-weekday-schedule | + | * clear-yearday-schedule | + | * get-holiday-schedule | + | * get-pin | + | * get-rfid | + | * get-user-type | + | * get-weekday-schedule | + | * get-yearday-schedule | + | * lock-door | + | * set-holiday-schedule | + | * set-pin | + | * set-rfid | + | * set-user-type | + | * set-weekday-schedule | + | * set-yearday-schedule | + | * unlock-door | + | * unlock-with-timeout | + | * discover | + | * read | + | * report | + +-------------------------------------------------------------------------------------+ +``` + +### groups + +```bash +Usage: + ./chip-tool groups command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Commands: | + +-------------------------------------------------------------------------------------+ + | * add-group | + | * add-group-if-identifying | + | * get-group-membership | + | * remove-all-groups | + | * remove-group | + | * view-group | + | * discover | + | * read | + +-------------------------------------------------------------------------------------+ +``` + +### iaszone + +```bash +Usage: + ./chip-tool iaszone command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Commands: | + +-------------------------------------------------------------------------------------+ + | * discover | + | * read | + | * write | + +-------------------------------------------------------------------------------------+ +``` + +### identify + +```bash +Usage: + ./chip-tool identify command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Commands: | + +-------------------------------------------------------------------------------------+ + | * identify | + | * identify-query | + | * discover | + | * read | + +-------------------------------------------------------------------------------------+ +``` + +### levelcontrol + +```bash +Usage: + ./chip-tool levelcontrol command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Commands: | + +-------------------------------------------------------------------------------------+ + | * move | + | * move-to-level | + | * move-to-level-with-on-off | + | * move-with-on-off | + | * step | + | * step-with-on-off | + | * stop | + | * stop-with-on-off | + | * discover | + | * read | + | * report | + +-------------------------------------------------------------------------------------+ +``` + +### onoff + +```bash +Usage: + ./chip-tool onoff command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Commands: | + +-------------------------------------------------------------------------------------+ + | * off | + | * on | + | * toggle | + | * discover | + | * read | + | * report | + +-------------------------------------------------------------------------------------+ +``` + +### onoff off [endpoint-id] + +Send the OFF command to the ONOFF cluster on the given endpoint. + +### onoff on [endpoint-id] + +Send the ON command to the ONOFF cluster on the given endpoint. + +### onoff toggle [endpoint-id] + +Send the TOGGLE command to the ONOFF cluster on the given endpoint. + +### onoff discover [endpoint-id] + +Send the DISCOVER command to the ONOFF cluster on the given endpoint. + +### pairing + +```bash +Usage: + ./chip-tool pairing command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Commands: | + +-------------------------------------------------------------------------------------+ + | * unpair | + | * ble | + | * softap | + +-------------------------------------------------------------------------------------+ +``` + +### payload + +```bash +Usage: + ./chip-tool payload command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Commands: | + +-------------------------------------------------------------------------------------+ + | * parse-setup-payload | + | * parse-additional-data-payload | + +-------------------------------------------------------------------------------------+ +``` + +### scenes + +```bash +Usage: + ./chip-tool scenes command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Commands: | + +-------------------------------------------------------------------------------------+ + | * add-scene | + | * get-scene-membership | + | * recall-scene | + | * remove-all-scenes | + | * remove-scene | + | * store-scene | + | * view-scene | + | * discover | + | * read | + +-------------------------------------------------------------------------------------+ +``` + +### temperaturemeasurement + +```bash +Usage: + ./chip-tool temperaturemeasurement command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Commands: | + +-------------------------------------------------------------------------------------+ + | * discover | + | * read | + | * report | + +-------------------------------------------------------------------------------------+ +``` + +To learn more about the tool, how to build it, use its commands and advanced +features, read the following guide: + +- [Working with the CHIP Tool](https://github.com/project-chip/connectedhomeip/tree/master/docs/guides/chip_tool_guide.md) diff --git a/_sources/examples/common/README.md b/_sources/examples/common/README.md new file mode 100644 index 000000000000..252f75f27327 --- /dev/null +++ b/_sources/examples/common/README.md @@ -0,0 +1,18 @@ +--- +orphan: true +--- + +# Examples common libraries + +## What is this? + +The purpose of this directory is to contain libraries, which are not part of +CHIP libraries nor provided by the CHIP, but still very useful for the CHIP +examples in order to provide specific functionalities. + +## Available libraries + +- **m5stack-tft** - TFT library for ESP32 platform. +- **QRCode** - QR Code generator library +- **screen-framework** - Framework for creating simple on screen user + interfaces. diff --git a/_sources/examples/common/pigweed/rpc_console/README.md b/_sources/examples/common/pigweed/rpc_console/README.md new file mode 100644 index 000000000000..80bad035ccdf --- /dev/null +++ b/_sources/examples/common/pigweed/rpc_console/README.md @@ -0,0 +1,68 @@ +--- +orphan: true +--- + +# CHIP RPC CONSOLE + +This python application provides a console for interacting with rpc-enabled chip +devices. + +The console uses the [pigweed pw_console](https://pigweed.dev/pw_console/), but +with customizations to work better with CHIP, including containing all rpc proto +files required for CHIP. + +- [CHIP RPC CONSOLE](#chip-rpc-console) + - [Building](#building) + - [Running](#running) + +--- + +## Building + +If this is the first time using the checkout the environment must first be +bootstrapped to install all dependencies. + +``` +$ source /scripts/bootstrap.sh +``` + +If bootstrap has previously been run, then simply activate. + +``` +$ source /scripts/activate.sh +``` + +The python console is built and installed in the venv using gn: + +``` +$ cd /examples/common/pigweed/rpc_console +$ gn gen out/debug +$ ninja -C out/debug +``` + +After building the output directory also contains a folder +(chip_rpc_console_wheels), with all the wheels required for the tool. These can +be used to install the console without needing the sdk. Simply install all the +wheels in the folder: + +``` +$ cd /examples/common/pigweed/rpc_console/out/debug +$ pip install chip_rpc_console_wheels/*.whl +``` + +## Running + +To start the console provide the path to the device, for example: + +``` +$ chip-console --device /dev/ttyUSB0 +``` + +Note that `chip-console` is an entry point for chip_rpc.console and could also +be run with `python -m chip_rpc.console`. + +An example RPC command: + +```python +rpcs.chip.rpc.Device.GetDeviceInfo() +``` diff --git a/_sources/examples/common/screen-framework/README.md b/_sources/examples/common/screen-framework/README.md new file mode 100644 index 000000000000..77f450e6127b --- /dev/null +++ b/_sources/examples/common/screen-framework/README.md @@ -0,0 +1,95 @@ +--- +orphan: true +--- + +# Simple Screen UI Framework + +## Overview + +This is a framework for creating simple user interfaces for devices with tiny +screens and just a few buttons. + +For example, the [M5Stack](http://m5stack.com/) ESP32 Basic Core IoT device has +a 320x240 TFT display and three push buttons. + +This framework enables a UI such as the following, where focus is indicated by +color, the left and middle buttons function as a single axis navpad, the right +button function as an action button, and the back button is provided by the +framework onscreen: + + +--------------------------------------+ + | < SCREEN TITLE | + | ------------ | + | | + | ITEM 1 | + | ITEM 2 | + | ITEM 3 | + | | + | | + | | + | | + | PREVIOUS NEXT ACTION | + +--------------------------------------+ + +## Features + +- stack of screens with system back button +- labeled buttons for navigation and action +- focus handling +- custom screen content +- virtual LEDs (VLEDs) + +## Screen Manager + +The screen manager maintains a stack of screens that are pushed and popped for +interaction. Each is drawn with a title, system back button, three button +labels, and custom screen content. The screen manager dispatches events to the +topmost screen, such as: + +- enter/exit events (including whether the screen was pushed or popped) +- focus events (for navigation) +- action events +- display events (lazily) + +If configured, virtual LEDs (VLEDs) are omnipresent and can be toggled at will. + +## Screen + +Screens provide a title and three button labels to the screen manager. They +handle events from the screen manager, and cooperate to ensure focus behaves +nicely. + +## Focus Handling + +Screens are created without focus, and indicate to the screen manager whether +they can receive focus. If so, the screen manager focuses them when they are +pushed, and subsequently dispatches focus next/previous events which the screen +can use for navigation before any action is performed. + +The screen can request the screen manager to focus the system back button, which +is always available except when there are no covered screens on the stack. In +this way, a list screen can wrap its focus of list items through the system back +button if it is available, while skipping it otherwise. + +Blur and unblur focus events allow a screen's focus state to be preserved when +it is covered by a pushed screen and restored when it is subsequently uncovered. + +In summary, screens collaborate with the screen manager to handle focus via the +following focus event types: + +- NONE: remove focus from screen completely +- BLUR: unfocus screen (but retain focus state) +- UNBLUR: restore focus state (that was retained when blurred) +- NEXT: navigate focus forward in screen (possibly requesting focus back + button) +- PREVIOUS: navigate focus forward (possibly requesting back button focus) + +## Typical Usage + +A list screen can provide multiple options to the user. Each list item can push +another screen on the stack with more items. In this way a hierarchy of screens +can be formed. + +The back button dismisses a screen much as "escape" or "cancel" would. It's +possible to push an informational screen that is not focusable and has no +interaction, such that the only action available is back. diff --git a/_sources/examples/common/tracing/README.md b/_sources/examples/common/tracing/README.md new file mode 100644 index 000000000000..9b3c5392bd4a --- /dev/null +++ b/_sources/examples/common/tracing/README.md @@ -0,0 +1,9 @@ +--- +orphan: true +--- + +# Trace Handlers + +These are trace message handlers which get registered with pw_trace_chip and +interpret the different CHIP messages to extract the useful information required +for test automation. diff --git a/_sources/examples/contact-sensor-app/nxp/k32w/k32w0/README.md b/_sources/examples/contact-sensor-app/nxp/k32w/k32w0/README.md new file mode 100644 index 000000000000..acef8060200e --- /dev/null +++ b/_sources/examples/contact-sensor-app/nxp/k32w/k32w0/README.md @@ -0,0 +1,861 @@ +# CHIP K32W061 Contact Sensor Example Application + +The Project CHIP K32W061 Contact Sensor Example uses buttons to test changing +the lock and device states and LEDs to show the state of these changes. You can +use this example as a reference for creating your own application. + +The example is based on +[Project CHIP](https://github.com/project-chip/connectedhomeip) and the NXP K32W +SDK, and a simulated contact sensor over a low-power, 802.15.4 Thread network. + +The example behaves as a Project CHIP accessory, that is a device that can be +paired into an existing Project CHIP network and can be controlled by this +network. + +
    + +- [CHIP K32W0 Contact Sensor Example Application](#chip-k32w061-contact-sensor-example-application) +- [Introduction](#introduction) + - [Bluetooth LE Advertising](#bluetooth-le-advertising) + - [Bluetooth LE Rendezvous](#bluetooth-le-rendezvous) +- [Device UI](#device-ui) +- [Building](#building) + - [Overwrite board config files](#overwrite-board-config-files) + - [Known issues building](#known-issues-building) +- [Long Idle Time ICD Support](#long-idle-time-icd-support) +- [Manufacturing data](#manufacturing-data) +- [Flashing and debugging](#flashing-and-debugging) +- [Pigweed Tokenizer](#pigweed-tokenizer) + - [Detokenizer script](#detokenizer-script) + - [Notes](#notes) + - [Known issues tokenizer](#known-issues-tokenizer) +- [NXP Ultrafast P256 ECC Library](#nxp-ultrafast-p256-ecc-library) + - [Building steps](#building-steps) +- [Tinycrypt ECC library](#tinycrypt-ecc-library) + - [Building steps](#building-steps-1) +- [OTA](#ota) + - [Writing the SSBL](#writing-the-ssbl) + - [Writing the PSECT](#writing-the-psect) + - [Writing the application](#writing-the-application) + - [OTA Testing](#ota-testing) + - [Known issues ota](#known-issues-ota) +- [Low power](#low-power) + - [Known issues low power](#known-issues-low-power) +- [Removing SSBL Upgrade region](#removing-ssbl-upgrade-region) + + + +## Introduction + +![K32W061 DK6](../../../../platform/nxp/k32w/k32w0/doc/images/k32w-dk6.jpg) + +The K32W061 contact sensor example application provides a working demonstration +of a connected contact sensor device, built using the Project CHIP codebase and +the NXP K32W061 SDK. The example supports remote access (e.g.: using CHIP Tool +from a mobile phone) and control of a simulated contact sensor over a low-power, +802.15.4 Thread network. It is capable of being paired into an existing Project +CHIP network along with other Project CHIP-enabled devices. + +The example targets the +[NXP K32W061 DK6](https://www.nxp.com/products/wireless/thread/k32w061-41-high-performance-secure-and-ultra-low-power-mcu-for-zigbeethread-and-bluetooth-le-5-0-with-built-in-nfc-option:K32W061_41) +development kit, but is readily adaptable to other K32W-based hardware. + +The CHIP device that runs the contact sensor application is controlled by the +CHIP controller device over the Thread protocol. By default, the CHIP device has +Thread disabled, and it should be paired over Bluetooth LE with the CHIP +controller and obtain configuration from it. The actions required before +establishing full communication are described below. + +The example also comes with a test mode, which allows to start Thread with the +default settings by pressing a button. However, this mode does not guarantee +that the device will be able to communicate with the CHIP controller and other +devices. + +### SE051H Secure Element + +Deployment of this firmware configuration requires the K32W061 board setups +using the K32W061 module board, SE051 Expansion board and Generic Expansion +board as shown below: + +![SE051H + K32W061 DK6](../../../../platform/nxp/k32w/k32w0/doc/images/k32w-se.jpg) + +The SE051H Secure Element extension may be used for best in class security and +offloading some of the Project CHIP cryptographic operations. Depending on your +hardware configuration, choose one of the options below (building with or +without Secure Element). NOTE: the SE051H is a derivative of the SE051 product +family (see http://www.nxp.com/SE051) including dedicated CHIP support in +addition to the SE051 feature set. See the material provided separately by NXP +for more details on SE051H. + +### Bluetooth LE Advertising + +In this example, to commission the device onto a Project CHIP network, it must +be discoverable over Bluetooth LE. For security reasons, you must start +Bluetooth LE advertising manually after powering up the device by pressing +Button USERINTERFACE. + +## LIT ICD Active Mode + +If the device is acting as a LIT ICD and it's already commissioned, then Button +USERINTERFACE can be pressed for forcing the switch to Active Mode. + +### Bluetooth LE Rendezvous + +In this example, the commissioning procedure (called rendezvous) is done over +Bluetooth LE between a CHIP device and the CHIP controller, where the controller +has the commissioner role. + +To start the rendezvous, the controller must get the commissioning information +from the CHIP device. The data payload is encoded within a QR code, printed to +the UART console and shared using an NFC tag. For security reasons, you must +start NFC tag emulation manually after powering up the device by pressing +Button 4. + +### Thread Provisioning + +Last part of the rendezvous procedure, the provisioning operation involves +sending the Thread network credentials from the CHIP controller to the CHIP +device. As a result, device is able to join the Thread network and communicate +with other Thread devices in the network. + +## Device UI + +The example application provides a simple UI that depicts the state of the +device and offers basic user control. This UI is implemented via the +general-purpose LEDs and buttons built in to the OM15082 Expansion board +attached to the DK6 board. + +**LED D2** shows the overall state of the device and its connectivity. Four +states are depicted: + +- _Short Flash On (50ms on/950ms off)_ — The device is in an + unprovisioned (unpaired) state and is waiting for a commissioning + application to connect. + +* _Rapid Even Flashing (100ms on/100ms off)_ — The device is in an + unprovisioned state and a commissioning application is connected via BLE. + +- _Short Flash Off (950ms on/50ms off)_ — The device is full + provisioned, but does not yet have full network (Thread) or service + connectivity. + +* _Solid On_ — The device is fully provisioned and has full network and + service connectivity. + +**LED D3** shows the state of the simulated contact sensor. when the LED is lit, +the sensor is contacted, when not lit, the sensor is non-contacted. + +**Button SW2** can be used to reset the device to a default state. A short Press +Button SW2 initiates a factory reset. After an initial period of 3 seconds, LED2 +D2 and D3 will flash in unison to signal the pending reset. After 6 seconds will +cause the device to reset its persistent configuration and initiate a reboot. +The reset action can be cancelled by press SW2 button at any point before the 6 +second limit. + +**Button SW3** can be used to change the state of the simulated contact sensor. +The button behaves as a toggle, swapping the state every time it is pressed. + +**Button SW4** can be used for initiating the OTA software update process. + +The remaining two LEDs (D1/D4) and button (SW1) are unused. + +Directly on the development board, **Button USERINTERFACE** can be used for +enabling Bluetooth LE advertising for a predefined period of time. Also, pushing +this button starts the NFC emulation by writing the onboarding information in +the NTAG. + +### No expansion board + +In case the **OM15082** Expansion board is not attached to the DK6 board, the +functionality of LED D2 and LED D3 is taken over by LED DS2, respectively LED +DS3, which can be found on the DK6 board. + +Also, by long pressing the **USERINTERFACE** button, the factory reset action +will be initiated. + +When low power is enabled, the **ISP button** on DK6 board is used to change +contact status. + +## Building + +In order to build the Project CHIP example, we recommend using a Linux +distribution (the demo-application was compiled on Ubuntu 20.04). + +Activate the Matter environment: + +```bash +user@ubuntu:~/Desktop/git/connectedhomeip$ source ./scripts/activate.sh +``` + +To bring the SDK in the environment, the user can: + +- download it with west tool, in which case it will be handled automatically + by gn: + + ```bash + user@ubuntu:~/Desktop/git/connectedhomeip$ cd third_party/nxp/k32w0_sdk/repo + user@ubuntu:~/Desktop/git/connectedhomeip/third_party/nxp/k32w0_sdk/repo$ west init -l manifest --mf west.yml + user@ubuntu:~/Desktop/git/connectedhomeip/third_party/nxp/k32w0_sdk/repo$ west update + ``` + + In case there are local modification to the already installed github NXP + SDK, use the below `west forall` command instead of the `west init` command + to reset the west workspace. Warning: all local changes will be lost after + running this command. + + ```bash + user@ubuntu:~/Desktop/git/connectedhomeip$ cd third_party/nxp/k32w0_sdk/repo + user@ubuntu:~/Desktop/git/connectedhomeip/third_party/nxp/k32w0_sdk/repo$ west forall -c "git reset --hard && git clean -xdf" -a + ``` + +- set up a custom path to the SDK, in which case + `k32w0_sdk_root=\"${NXP_K32W0_SDK_ROOT}\"` must be added to the `gn gen` + command: + + ``` + user@ubuntu:~/Desktop/git/connectedhomeip$ export NXP_K32W0_SDK_ROOT=/custom/path/to/SDK + ``` + +Start building the application: + +```bash +user@ubuntu:~/Desktop/git/connectedhomeip$ cd examples/contact-sensor-app/nxp/k32w/k32w0 +user@ubuntu:~/Desktop/git/connectedhomeip/examples/contact-sensor-app/nxp/k32w/k32w0$ gn gen out/debug +user@ubuntu:~/Desktop/git/connectedhomeip/examples/contact-sensor-app/nxp/k32w/k32w0$ ninja -C out/debug +``` + +To build with Secure Element, follow the same steps as above but set +`chip_with_se05x=1 chip_enable_ota_requestor=false` in the `gn gen` command. + +Note that option `chip_enable_ota_requestor=false` is required for building with +Secure Element due to flash constraints. + +- K32W041AM flavor + + Exactly the same steps as above but set argument `build_for_k32w041am=1` in + the gn command. + +Also, in case the OM15082 Expansion Board is not attached to the DK6 board, the +build argument (chip_with_OM15082) inside the gn build instruction should be set +to zero. The argument chip_with_OM15082 is set to zero by default. + +In case that Openthread CLI is needed, chip_with_ot_cli build argument must be +set to 1. + +In case the board doesn't have 32KHz crystal fitted, one can use the 32KHz free +running oscillator as a clock source. In this case one must set the use_fro_32k +argument to 1. + +K32W0x1 supports antenna diversity feature, which is a technique that maximizes +the performance of an antenna system, allowing the radio signal to be switched +between two antennas that have very low correlation between their received +signals. Typically, this is achieved by spacing two antennas around 0.25 +wavelengths apart or by using 2 orthogonal types of polarization. This is +controlled by software. K32W0x1 provides an output (`ADO`) on one of `DIO7`, +`DIO9` or `DIO19` and optionally its complement (`ADE`) on `DIO6` that can be +used to control an antenna switch. In order to use this feature, user must set +`use_antenna_diversity` to 1. + +In case signing errors are encountered when running the "sign_images.sh" script +(run automatically) install the recommanded packages (python version > 3, pip3, +pycrypto, pycryptodome): + +``` +user@ubuntu:~$ python3 --version +Python 3.8.2 +user@ubuntu:~$ pip3 --version +pip 20.0.2 from /usr/lib/python3/dist-packages/pip (python 3.8) +user@ubuntu:~$ pip3 list | grep -i pycrypto +pycrypto 2.6.1 +pycryptodome 3.9.8 +``` + +The resulting output file can be found in out/debug/chip-k32w0x-contact-example. + +## Long Idle Time ICD Support + +By default, contact-sensor is compiled as SIT ICD (Short Idle Time +Intermittently Connected Device) - see rules from k32w0_sdk.gni: + +``` +chip_ot_idle_interval_ms = 2000 # 2s Idle Intervals +chip_ot_active_interval_ms = 500 # 500ms Active Intervals + +nxp_idle_mode_duration_s = 600 # 10min Idle Mode Interval +nxp_active_mode_duration_ms = 10000 # 10s Active Mode Interval +nxp_active_mode_threshold_ms = 1000 # 1s Active Mode Threshold +nxp_icd_supported_clients_per_fabric = 2 # 2 registration slots per fabric +``` + +If LIT ICD support is needed then `chip_enable_icd_lit=true` must be specified +as gn argument and the above parameters can be modified to comply with LIT +requirements (e.g.: LIT devices must configure +`chip_ot_idle_interval_ms > 15000`). Example LIT configuration: + +``` +chip_ot_idle_interval_ms = 15000 # 15s Idle Intervals +chip_ot_active_interval_ms = 500 # 500ms Active Intervals + +nxp_idle_mode_duration_s = 3600 # 60min Idle Mode Interval +nxp_active_mode_duration_ms = 0 # 0 Active Mode Interval +nxp_active_mode_threshold_ms = 30000 # 30s Active Mode Threshold +``` + +ICD parameters that may be disabled once LIT functionality is enabled: + +``` +chip_persist_subscriptions: try to re-establish subscriptions from the server side after reboot +chip_subscription_timeout_resumption: same as above but retries are using a Fibonacci backoff +``` + +### Overwrite board config files + +The example uses template/reference board configuration files. + +To overwrite the board configuration files, set `override_is_DK6=false` in the +`k32w0_sdk` target from the app `BUILD.gn`: + +``` +k32w0_sdk("sdk") { + override_is_DK6 = false + ... +} +``` + +This variable will be used by `k32w0_sdk.gni` to overwrite `chip_with_DK6` +option, thus the reference board configuration files will no longer be used. + +### Known issues building + +- When using Secure element and cross-compiling on Linux, log messages from + the Plug&Trust middleware stack may not echo to the console. + +## Rotating device id + +This is an optional feature and can be used in multiple ways (please see section +5.4.2.4.5 from Matter specification). One use case is Amazon Frustration Free +Setup, which leverages the C3 Characteristic (Additional commissioning-related +data) to offer an easier way to set up the device. The rotating device id will +be encoded in this additional data and is programmed to rotate at pre-defined +moments. The algorithm uses a unique per-device identifier that must be +programmed during factory provisioning. + +Please use the following build args: + +- `chip_enable_rotating_device_id=1` - to enable rotating device id. +- `chip_enable_additional_data_advertising=1` - to enable C3 characteristic. + +## Manufacturing data + +See +[Guide for writing manufacturing data on NXP devices](../../../../../guides/nxp/nxp_manufacturing_flow.md). + +There are factory data generated binaries available in +examples/platform/nxp/k32w/k32w0/scripts/demo_generated_factory_data folder. +These are based on the DAC, PAI and PAA certificates found in +scripts/tools/nxp/demo_generated_certs folder. The demo_factory_data_dut1.bin +uses the DAC certificate and private key found in +examples/platform/nxp/k32w/k32w0/scripts/demo_generated_factory_data/dac/dut1 +folder. The demo_factory_data_dut2.bin uses the DAC certificate and private key +found in +examples/platform/nxp/k32w/k32w0/scripts/demo_generated_factory_data/dac/dut2 +folder. These two factory data binaries can be used for testing topologies with +2 DUTS. They contain the corresponding DACs/PAIs generated using +generate_nxp_chip_factory_bin.py script. The discriminator is 14014 and the +passcode is 1000. These demo certificates are working with the CDs installed in +CHIPProjectConfig.h. + +Regarding factory data provider, there are two options: + +- use the default factory data provider: `FactoryDataProviderImpl` by setting + `chip_with_factory_data=1` in the gn build command. +- use a custom factory data provider: please see + [Guide for implementing a custom factory data provider](../../../../platform/nxp/k32w/k32w0/common/README.md). + This can be enabled when `chip_with_factory_data=1` by setting + `use_custom_factory_provider=1` in the gn build command. + +## Flashing and debugging + +Program the firmware using the official +[OpenThread Flash Instructions](https://github.com/openthread/ot-nxp/tree/main/src/k32w0/k32w061#flash-binaries). + +All you have to do is to replace the Openthread binaries from the above +documentation with _out/debug/chip-k32w0x-contact-example.bin_ if DK6Programmer +is used or with _out/debug/chip-k32w0x-contact-example_ if MCUXpresso is used. + +## Pigweed tokenizer + +The tokenizer is a pigweed module that allows hashing the strings. This greatly +reduces the flash needed for logs. The module can be enabled by building with +the gn argument _chip_pw_tokenizer_logging=true_. The detokenizer script is +needed for parsing the hashed scripts. + +### Detokenizer script + +The python3 script detokenizer.py is a script that decodes the tokenized logs +either from a file or from a serial port. It is located in the following path +`examples/platform/nxp/k32w/k32w0/scripts/detokenizer.py`. + +The script can be used in the following ways: + +``` +usage: detokenizer.py serial [-h] -i INPUT -d DATABASE [-o OUTPUT] +usage: detokenizer.py file [-h] -i INPUT -d DATABASE -o OUTPUT +``` + +The first parameter is either _serial_ or _file_ and it selects between decoding +from a file or from a serial port. + +The second parameter is _-i INPUT_ and it must se set to the path of the file or +the serial to decode from. + +The third parameter is _-d DATABASE_ and represents the path to the token +database to be used for decoding. The default path is +_out/debug/chip-k32w0x-contact-example-database.bin_ after a successful build. + +The forth parameter is _-o OUTPUT_ and it represents the path to the output file +where the decoded logs will be stored. This parameter is required for file usage +and optional for serial usage. If not provided when used with serial port, it +will show the decoded log only at the stdout and not save it to file. + +### Notes + +The token database is created automatically after building the binary if the +argument _chip_pw_tokenizer_logging=true_ was used. + +The detokenizer script must be run inside the example's folder after a +successful run of the _scripts/activate.sh_ script. The pw_tokenizer module used +by the script is loaded by the environment. An example of running the +detokenizer script to see logs of a contact-sensor app: + +``` +python3 ../../../../../examples/platform/nxp/k32w/k32w0/scripts/detokenizer.py serial -i /dev/ttyACM0 -d out/debug/chip-k32w0x-contact-example-database.bin -o device.txt +``` + +### Known issues tokenizer + +The building process will not update the token database if it already exists. In +case that new strings are added and the database already exists in the output +folder, it must be deleted so that it will be recreated at the next build. + +Not all tokens will be decoded. This is due to a gcc/pw_tokenizer issue. The +pw_tokenizer creates special elf sections using attributes where the tokens and +strings will be stored. This sections will be used by the database creation +script. For template C++ functions, gcc ignores these attributes and places all +the strings by default in the .rodata section. As a result the database creation +script won't find them in the special-created sections. + +If run, closed and rerun with the serial option on the same serial port, the +detokenization script will get stuck and not show any logs. The solution is to +unplug and plug the board and then rerun the script. + +## NXP Ultrafast P256 ECC Library + +### Building steps + +By default, the application builds with NXP Ultrafast P256 ECC Library. To build +with this library, use the following arguments: + +- Build without Secure element (_chip_with_se05x=0_) and with crypto platform + (_chip_crypto=\"platform\"_). + +To stop using Ultrafast P256 ECC Library, simply build with +_chip_crypto=\"mbedtls\"_ or with Tinycrypt. + +## Tinycrypt ECC library + +### Building steps + +In order to use the Tinycrypt ECC library, use the following build arguments: + +- Build without Secure element (_chip_with_se05x=0_), with crypto platform + (_chip_crypto=\"platform\"_) and with tinycrypt selected + (_chip_crypto_flavor=\"tinycrypt\"_). + +## OTA + +The internal flash needs to be prepared for the OTA process. First 16K of the +internal flash needs to be populated with a Secondary Stage Bootloader (SSBL) +related data while the last 8.5K of flash space is holding image directory +related data (PSECT). The space between these two zones will be filled by the +application. + +### Writing the SSBL + +The SDK already provides an SSBL binary compiled with external flash support: +`boards/k32w061dk6/wireless_examples/framework/ssbl/binary/ssbl_ext_flash_pdm_support.bin`, +but it does not offer multi-image OTA support. + +Alternatively, the SSBL can ge generated from one of the SDK demo examples. The +SSBL demo application can be imported from the `Quickstart panel`: +`Import SDK example(s) -> select wireless -> framework -> ssbl` application. + +![SSBL Application Select](../../../../platform/nxp/k32w/k32w0/doc/images/ssbl_select.JPG) + +### Features + +#### Multi image + +To support multi-image OTA feature, the SSBL project must be compiled using the +following defines: + +- `PDM_EXT_FLASH=1` - support PDM in external flash. +- `gOTAUseCustomOtaEntry=1` - support custom OTA entry for multi-image. +- `gOTACustomOtaEntryMemory=OTACustomStorage_ExtFlash` - K32W0 uses + `OTACustomStorage_ExtFlash` (1) by default. +- `SPIFI_DUAL_MODE_SUPPORT=1` - only for configurations that use dual `SPIFI` + flash (e.g. K32W041AM variant). + +Optionally, add the following defines: + +- `SPIFI_OPTIM_SIZE=1` - to optimize SSBL size. +- `EXTERNAL_FLASH_DATA_OTA=1` - to support external read only data. + +![SSBL_MULTI_IMAGE](../../../../platform/nxp/k32w/k32w0/doc/images/ssbl_multi_image.JPG) + +#### Simple hash verification + +When secure boot is not used, a simple hash can be appended at the end of the +image for integrity check. Applications should be built with +`chip_simple_hash_verification=1`. + +To support simple hash verification feature, the SSBL project must be compiled +with: + +- `gSimpleHashVerification=1` + +and update the post-build command to use simple hash verification instead of the +default options. Go to +`Project -> Properties -> C/C++ Build -> Settings -> Build steps` and press +`Edit` under `Post-build steps` subsection. The command should look similar to: + +![SSBL_SIMPLE_HASH_VERIFICATION](../../../../platform/nxp/k32w/k32w0/doc/images/ssbl_simple_hash.JPG) + +Once compiled, the required SSBL file is called `k32w061dk6_ssbl.bin`. + +![SSBL_BIN](../../../../platform/nxp/k32w/k32w0/doc/images/ssbl_bin.JPG) + +Before writing the SSBL, it it recommanded to fully erase the internal flash: + +``` +DK6Programmer.exe -V 5 -P 1000000 -s -e Flash +``` + +`k32w061dk6_ssbl.bin` must be written at address 0 in the internal flash: + +``` +DK6Programmer.exe -V2 -s -P 1000000 -Y -p FLASH@0x00="k32w061dk6_ssbl.bin" +``` + +### Writing the PSECT + +This is the list of all supported partitions: + +``` +0000000010000000 : SSBL partition + + 00000000 -----------> Start Address + 1000 ---------------> 0x0010 Number of 512-bytes pages + 00 -----------------> 0x00 Bootable flag + 00 -----------------> 0x00 Image type (0x00 = SSBL) + +00400000c9040101: Application partition + + 00400000 -----------> 0x00004000 Start Address + c904 ---------------> 0x04c9 Number of 512-bytes pages + 01 -----------------> 0x01 Bootable flag + 01 -----------------> 0x01 Image type (0x01 = Application) + +00000010800000fe: Ext Flash text partition + + 00000010 -----------> 0x10000000 Start Address (external flash) + 8000 ---------------> 0x0080 Number of 512-bytes pages + 00 -----------------> 0x00 Bootable flag + fe -----------------> 0xFE Image type (0xFE = Ext Flash text) + +00000110300200fc : OTA Image partition + + 00000110 -----------> 0x10010000 Start Address + 3002----------------> 0x0230 Number of 512-bytes pages + 00 -----------------> 0x00 Bootable flag + fc -----------------> 0xFC Image type (0xFC = OTA partition) + +00000510100000fd: NVM partition + + 00000510 -----------> 0x10050000 Start Address + 1000 ---------------> 0x0010 Number of 512-bytes pages + 00 -----------------> 0x00 Bootable flag + fd -----------------> 0xFD Image type (0xFD = NVM partition) +``` + +First, image directory 0 (SSBL partition) must be written: + +``` +DK6Programmer.exe -V5 -s -P 1000000 -w image_dir_0=0000000010000000 +``` + +Here is the interpretation of the fields: + +``` +00000000 -> start address 0x00000000 +1000 -> size = 0x0010 pages of 512-bytes (= 8kB) +00 -> not bootable (only used by the SSBL to support SSBL update) +00 -> SSBL Image Type +``` + +Second, image directory 1 (application partition) must be written: + +``` +DK6Programmer.exe -V5 -s -P 1000000 -w image_dir_1=00400000C9040101 +``` + +Here is the interpretation of the fields: + +``` +00400000 -> start address 0x00004000 +C904 -> 0x4C9 pages of 512-bytes (= 612.5kB) +01 -> bootable flag +01 -> image type for the application +``` + +Please note the user can write additional partitions by writing +`image_dir_2/3/4` with the wanted configuration. + +### Writing the application + +DK6Programmer can be used for flashing the application: + +``` +DK6Programmer.exe -V2 -s -P 1000000 -Y -p FLASH@0x4000="chip-k32w0x-contact-example.bin" +``` + +If debugging is needed, MCUXpresso can be used then for flashing the +application. Please make sure that the application is written at address 0x4000: + +![FLASH_LOCATION](../../../../platform/nxp/k32w/k32w0/doc/images/flash_location.JPG) + +### OTA Testing + +The OTA topology used for OTA testing is illustrated in the figure below. +Topology is similar with the one used for Matter Test Events. + +![OTA_TOPOLOGY](../../../../platform/nxp/k32w/k32w0/doc/images/ota_topology.JPG) + +The concept for OTA is the next one: + +- there is an OTA Provider Application that holds the OTA image. In our case, + this is a Linux application running on an Ubuntu based-system; +- the OTA Requestor functionality is embedded inside the Lighting Application. + It will be used for requesting OTA blocks from the OTA Provider; +- the controller (a linux application called chip-tool) will be used for + commissioning both the device and the OTA Provider App. The device will be + commissioned using the standard Matter flow (BLE + IEEE 802.15.4) while the + OTA Provider Application will be commissioned using the _onnetwork_ option + of chip-tool; +- during commissioning, each device is assigned a node id by the chip-tool + (can be specified manually by the user). Using the node id of the device and + of the lighting application, chip-tool triggers the OTA transfer by invoking + the _announce-ota-provider_ command - basically, the OTA Requestor is + informed of the node id of the OTA Provider Application. + +_Computer #1_ can be any system running an Ubuntu distribution. We recommand +using TE 7.5 instructions from +[here](https://groups.csa-iot.org/wg/matter-csg/document/24839), where RPi 4 are +proposed. Also, TE 7.5 instructions document point to the OS/Docker images that +should be used on the RPis. For compatibility reasons, we recommand compiling +chip-tool and OTA Provider applications with the same commit id that was used +for compiling the Lighting Application. Also, please note that there is a single +controller (chip-tool) running on Computer #1 which is used for commissioning +both the device and the OTA Provider Application. If needed, +[these instructions](https://itsfoss.com/connect-wifi-terminal-ubuntu/) could be +used for connecting the RPis to WiFi. + +Build the Linux OTA provider application: + +``` +user@computer1:~/connectedhomeip$ : ./scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/ota-provider-app chip_config_network_layer_ble=false +``` + +Build Linux chip-tool: + +``` +user@computer1:~/connectedhomeip$ : ./scripts/examples/gn_build_example.sh examples/chip-tool out/chip-tool-app +``` + +Build OTA image: + +In order to build an OTA image, use NXP wrapper over the standard tool +`src/app/ota_image_tool.py`: + +- `scripts/tools/nxp/ota/ota_image_tool.py`. + +The tool can be used to generate an OTA image with the following format: + +``` + | OTA image header | TLV1 | TLV2 | ... | TLVn | +``` + +where each TLV is in the form `|tag|length|value|`. + +Note that "standard" TLV format is used. Matter TLV format is only used for +factory data TLV value. + +A user can select which default processors to enable: + +- `chip_enable_ota_firmware_processor=1` to enable default firmware (app/SSBL) + update processor (enabled by default). +- `chip_enable_ota_factory_data_processor=1` to enable default factory data + update processor (disabled by default). + +The address for storing the custom OTA entry can also be specified: + +- `ota_custom_entry_address="0x000C1000"` is the default value, where + `0x000C1000` is the end address of the PDM area. PDM area ends at + `0x00100000` (top of external flash) and has a size of `63 * 4096` bytes. + The user should be aware of the external flash configuration and use an + address that does not overlap with anything else. + +Please see more in the +[OTA image tool guide](https://github.com/project-chip/connectedhomeip/blob/master/scripts/tools/nxp/ota/README.md). + +Here is an example that generates an OTA image with application update TLV: + +``` +./scripts/tools/nxp/ota/ota_image_tool.py create -v 0xDEAD -p 0xBEEF -vn 42021 -vs "1.0" -da sha256 --app-input-file chip-k32w0x-contact-example.bin chip-k32w0x-contact-example.ota +``` + +A note regarding OTA image header version (`-vn` option). An application binary +has its own software version, given by +`CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION` (`42020` by default), which can be +overwritten. For having a correct OTA process, the OTA header version should be +the same as the binary embedded software version. A user can set a custom +software version in the gn build args by setting `chip_software_version` to the +wanted version. + +Start the OTA Provider Application: + +``` +user@computer1:~/connectedhomeip$ : rm -rf /tmp/chip_* +user@computer1:~/connectedhomeip$ : ./out/ota-provider-app/chip-ota-provider-app -f chip-k32w0x-contact-example.ota +``` + +Provision the OTA provider application and assign node id _1_. Also, grant ACL +entries to allow OTA requestors: + +``` +user@computer1:~/connectedhomeip$ : rm -rf /tmp/chip_* +user@computer1:~/connectedhomeip$ : ./out/chip-tool-app/chip-tool pairing onnetwork 1 20202021 +user@computer1:~/connectedhomeip$ : ./out/chip-tool-app/chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": null}]' 1 0 +``` + +Provision the device and assign node id _2_: + +``` +user@computer1:~/connectedhomeip$ : ./out/chip-tool-app/chip-tool pairing ble-thread 2 hex: 20202021 3840 +``` + +Start the OTA process: + +``` +user@computer1:~/connectedhomeip$ : ./out/chip-tool-app/chip-tool otasoftwareupdaterequestor announce-otaprovider 1 0 0 0 2 0 +``` + +### Known issues ota + +- SRP cache on the openthread border router needs to flushed each time a new + commissioning process is attempted. For this, factory reset the device, then + execute _ot-ctl server disable_ followed by _ot-ctl server enable_. After + this step, the commissioning process of the device can start; +- Due to some MDNS issues, the commissioning of the OTA Provider Application + may fail. Please make sure that the SRP cache is disabled (_ot-ctl srp + server disable_) on the openthread border router while commissioning the OTA + Provider Application; +- No other Docker image should be running (e.g.: Docker image needed by Test + Harness) except the OTBR one. A docker image can be killed using the + command: + +``` +user@computer1:~/connectedhomeip$ : sudo docker kill $container_id +``` + +- In order to avoid MDNS issues, only one interface should be active at one + time. E.g.: if WiFi is used then disable the Ethernet interface and also + disable multicast on that interface: + +``` +user@computer1:~/connectedhomeip$ sudo ip link set dev eth0 down +user@computer1:~/connectedhomeip$ sudo ifconfig eth0 -multicast +``` + +- If OTBR Docker image is used, then the "-B" parameter should point to the + interface used for the backbone. + +- If Wi-Fi is used on a RPI4, then a 5Ghz network should be selected. + Otherwise, issues related to BLE-WiFi combo may appear. + +## Low power + +The example also offers the possibility to run in low power mode. This means +that the board will go in a deep power down mode most of the time and the power +consumption will be very low. + +In order to build with low power support, the _chip_with_low_power=1_ must be +provided to the build system. In this case, please note that the GN build +arguments _chip_with_OM15082_ and _chip_with_ot_cli_ must be set to 0 and +_chip_logging_ must be set to false to disable logging. + +In order to maintain a low power consumption, the LEDs showing the state of the +elock and the internal state are disabled. Console logs can be used instead. +Also, please note that once the board is flashed with MCUXpresso the debugger +disconnects because the board enters low power. + +Power Measurement Tool can be used inside MCUXpresso for checking the power +consumption pattern: Window -> Show View -> Other -> Power Measurement Tool. The +configuration for this tool is the next one: + +![POWER_CONF](../../../../platform/nxp/k32w/k32w0/doc/images/power_conf.JPG) + +Also, please make sure that the J14 jumper is set to the _ENABLED_ position and +no expansion board is attached to the DK6. A view from this tool is illustrated +below: + +![POWER_VIEW](../../../../platform/nxp/k32w/k32w0/doc/images/power_view.JPG) + +Please note that that the Power Measurement Tool is not very accurate and +professional tools must be used if exact power consumption needs to be known. + +### Known issues low power + +- Power Measurement Tool may not work correctly in MCUXpresso versions greater + that 11.0.1. + +## Removing SSBL Upgrade Region + +The example also offers the possibility to remove SSBL upgrade region, for +reserving more space for application level. + +A new flag `chip_reduce_ssbl_size` is introduced. In order to remove the SSBL +upgrade region, `chip_reduce_ssbl_size=true` must be provided to the build +system + +The programming method will change: + +- writing image directory 1 should change to + + ``` + DK6Programmer.exe -V5 -s -P 1000000 -w image_dir_1=00200000D9040101 + ``` + + Here is the interpretation of the fields: + + ``` + 00200000 -> start address 0x00002000 + D904 -> 0x4D9 pages of 512-bytes (= 620.5kB) + 01 -> bootable flag + 01 -> image type for the application + ``` + +- Matter application offset address should change to + ``` + DK6Programmer.exe -V2 -s -P 1000000 -Y -p FLASH@0x2000="chip-k32w0x-contact-example.bin" + ``` diff --git a/_sources/examples/contact-sensor-app/nxp/k32w/k32w1/README.md b/_sources/examples/contact-sensor-app/nxp/k32w/k32w1/README.md new file mode 100644 index 000000000000..a6952323829d --- /dev/null +++ b/_sources/examples/contact-sensor-app/nxp/k32w/k32w1/README.md @@ -0,0 +1,465 @@ +# Matter K32W1 Contact Sensor Example Application + +Matter K32W1 Contact Sensor Example uses buttons to test changing the lock and +device states and LEDs to show the state of these changes. You can use this +example as a reference for creating your own application. + +The example is based on +[Matter](https://github.com/project-chip/connectedhomeip) and the NXP K32W1 SDK, +and a simulated contact sensor over a low-power, 802.15.4 Thread network. + +The example behaves as a Matter accessory, that is a device that can be paired +into an existing Matter network and can be controlled by this network. + +
    + +- [Matter K32W1 Contact Sensor Example Application](#matter-k32w1-contact-sensor-example-application) +- [Introduction](#introduction) + - [Bluetooth LE Advertising](#bluetooth-le-advertising) + - [Bluetooth LE Rendezvous](#bluetooth-le-rendezvous) +- [Device UI](#device-ui) +- [Building](#building) +- [Long Idle Time ICD Support](#long-idle-time-icd-support) +- [Manufacturing data](#manufacturing-data) +- [Flashing](#flashing) + - [Flashing the NBU image](#flashing-the-nbu-image) + - [Flashing the host image](#flashing-the-host-image) +- [Debugging](#debugging) +- [OTA](#ota) + - [Convert srec into sb3 file](#convert-srec-into-sb3-file) + - [Convert sb3 into ota file](#convert-sb3-into-ota-file) + - [Running OTA](#running-ota) + - [Known issues](#known-issues) +- [Low power](#low-power) + + + +## Introduction + +![K32W1 EVK](../../../../platform/nxp/k32w/k32w1/doc/images/k32w1-evk.jpg) + +The K32W1 contact sensor example application provides a working demonstration of +a connected contact sensor device, built using the Matter codebase and the NXP +K32W1 SDK. The example supports remote access (e.g.: using CHIP Tool from a +mobile phone) and control of a simulated contact sensor over a low-power, +802.15.4 Thread network. It is capable of being paired into an existing Matter +network along with other Matter-enabled devices. + +The Matter device that runs the contact sensor application is controlled by the +Matter controller device over the Thread protocol. By default, the Matter device +has Thread disabled, and it should be paired over Bluetooth LE with the Matter +controller and obtain configuration from it. The actions required before +establishing full communication are described below. + +### Bluetooth LE Advertising + +In this example, to commission the device onto a Matter network, it must be +discoverable over Bluetooth LE. For security reasons, you must start Bluetooth +LE advertising manually after powering up the device by pressing Button SW2. + +### Bluetooth LE Rendezvous + +In this example, the commissioning procedure (called rendezvous) is done over +Bluetooth LE between a Matter device and the Matter controller, where the +controller has the commissioner role. + +To start the rendezvous, the controller must get the commissioning information +from the Matter device. The data payload is encoded within a QR code, or printed +to the UART console. + +### Thread Provisioning + +## Device UI + +The example application provides a simple UI that depicts the state of the +device and offers basic user control. This UI is implemented via the +general-purpose LEDs and buttons built in the K32W1 EVK board. + +**LED 2** shows the overall state of the device and its connectivity. Four +states are depicted: + +- _Short Flash On (50ms on/950ms off)_ — The device is in an + unprovisioned (unpaired) state and is waiting for a commissioning + application to connect. + +* _Rapid Even Flashing (100ms on/100ms off)_ — The device is in an + unprovisioned state and a commissioning application is connected via BLE. + +- _Short Flash Off (950ms on/50ms off)_ — The device is full + provisioned, but does not yet have full network (Thread) or service + connectivity. + +* _Solid On_ — The device is fully provisioned and has full network and + service connectivity. + +NOTE: LED2 will be disabled when CHIP_DEVICE_CONFIG_ENABLE_OTA_REQUESTOR is +enabled. On K32W1 EVK board, `PTB0` is wired to `LED2` also is wired to CS (Chip +Select) External Flash Memory. OTA image is stored in external memory because of +it's size. If LED2 is enabled then it will affect External Memory CS and OTA +will not work. + +**RGB LED** shows the state of the simulated contact sensor. when the LED is +lit, the sensor is contacted, when not lit, the sensor is non-contacted. + +**Button SW2**. SHORT press function is overloaded depending on the device type +and commissioning state. If the device is not commissioned, a SHORT press of the +button will enable Bluetooth LE advertising for a predefined period of time. If +the device is commissioned and is acting as a LIT ICD then a SHORT press of the +button will enable Active Mode. A LONG Press of Button SW2 initiates a factory +reset. After an initial period of 3 seconds, LED 2 and RGB LED will flash in +unison to signal the pending reset. After 6 seconds will cause the device to +reset its persistent configuration and initiate a reboot. The reset action can +be cancelled by press SW2 button at any point before the 6 second limit. + +**Button SW3** can be used to change the state of the simulated contact sensor. +The button behaves as a toggle, swapping the state every time it is short +pressed. When long pressed, it does a clean soft reset that takes into account +Matter shutdown procedure. + +## Building + +In order to build the Matter example, we recommend using a Linux distribution +(the demo-application was compiled on Ubuntu 20.04). + +- Download [K32W1 SDK for Matter](https://mcuxpresso.nxp.com/). Creating an + nxp.com account is required before being able to download the SDK. Once the + account is created, login and follow the steps for downloading K32W1 SDK. + The SDK Builder UI selection should be similar with the one from the image + below. + ![MCUXpresso SDK Download](../../../../platform/nxp/k32w/k32w1/doc/images/mcux-sdk-download.jpg) + +``` +user@ubuntu:~/Desktop/git/connectedhomeip$ export NXP_K32W1_SDK_ROOT=/home/user/Desktop/SDK_K32W1/ +user@ubuntu:~/Desktop/git/connectedhomeip$ source ./scripts/activate.sh +user@ubuntu:~/Desktop/git/connectedhomeip$ scripts/checkout_submodules.py --shallow --platform nxp --recursive +user@ubuntu:~/Desktop/git/connectedhomeip$ cd examples/contact-sensor-app/nxp/k32w/k32w1 +user@ubuntu:~/Desktop/git/connectedhomeip/examples/contact-sensor-app/nxp/k32w/k32w1$ gn gen out/debug +user@ubuntu:~/Desktop/git/connectedhomeip/examples/contact-sensor-app/nxp/k32w/k32w1$ ninja -C out/debug +``` + +In case that Openthread CLI is needed, chip_with_ot_cli build argument must be +set to 1. + +After a successful build, the `elf` and `srec` files are found in `out/debug/` - +`see the files prefixed with chip-k32w1-contact-example`. + +## Long Idle Time ICD Support + +By default, contact-sensor is compiled as SIT ICD (Short Idle Time +Intermittently Connected Device) - see rules from k32w1_sdk.gni: + +``` +chip_ot_idle_interval_ms = 2000 # 2s Idle Intervals +chip_ot_active_interval_ms = 500 # 500ms Active Intervals + +nxp_idle_mode_duration_s = 600 # 10min Idle Mode Interval +nxp_active_mode_duration_ms = 10000 # 10s Active Mode Interval +nxp_active_mode_threshold_ms = 1000 # 1s Active Mode Threshold +nxp_icd_supported_clients_per_fabric = 2 # 2 registration slots per fabric +``` + +If LIT ICD support is needed then `chip_enable_icd_lit=true` must be specified +as gn argument and the above parameters can be modified to comply with LIT +requirements (e.g.: LIT devices must configure +`chip_ot_idle_interval_ms > 15000`). Example LIT configuration: + +``` +chip_ot_idle_interval_ms = 15000 # 15s Idle Intervals +chip_ot_active_interval_ms = 500 # 500ms Active Intervals + +nxp_idle_mode_duration_s = 3600 # 60min Idle Mode Interval +nxp_active_mode_duration_ms = 0 # 0 Active Mode Interval +nxp_active_mode_threshold_ms = 30000 # 30s Active Mode Threshold +``` + +ICD parameters that may be disabled once LIT functionality is enabled: + +``` +chip_persist_subscriptions: try once to re-establish subscriptions from the server side after reboot +chip_subscription_timeout_resumption: same as above + try to re-establish timeout out subscriptions +using Fibonacci backoff for retries pacing. +``` + +## Manufacturing data + +Use `chip_with_factory_data=1` in the gn build command to enable factory data. + +For a full guide on manufacturing flow, please see +[Guide for writing manufacturing data on NXP devices](../../../../../guides/nxp/nxp_manufacturing_flow.md). + +## Flashing + +Two images must be written to the board: one for the host (CM33) and one for the +`NBU` (CM3). + +The image needed on the host side is the one generated in `out/debug/` while the +one needed on the `NBU` side can be found in the downloaded NXP-SDK package at +path - +`middleware\wireless\ieee-802.15.4\bin\k32w1\k32w1_nbu_ble_15_4_dyn_matter_$version.sb3`. + +### Flashing the `NBU` image + +`NBU` image should be written only when a new NXP-SDK is released. + +[K32W148 board quick start guide](https://www.nxp.com/document/guide/getting-started-with-the-k32w148-development-platform:GS-K32W148EVK) +can be used for updating the `NBU/radio` core: + +- Section 2.5 – Get Software – install `SPSDK` (Secure Provisioning Command + Line Tool) +- Section 3.3 – Updating `NBU` for Wireless examples - use the corresponding + `.sb3` file found in the SDK package at path + `middleware\wireless\ieee-802.15.4\bin\k32w1\` + +### Flashing the host image + +Host image is the one found under `out/debug/`. It should be written after each +build process. + +If debugging is needed then jump directly to the [Debugging](#debugging) +section. Otherwise, if only flashing is needed then +[JLink 7.84b](https://www.segger.com/downloads/jlink/) can be used: + +- Plug K32W1 to the USB port (no need to keep the SW4 button pressed while + doing this) + +- Create a new file, `commands_script`, with the following content (change + application name accordingly): + +```bash +reset +halt +loadfile chip-k32w1-contact-example.srec +reset +go +quit +``` + +- copy the application and `commands_script` in the same folder that JLink + executable is placed. Execute: + +```bash +$ jlink -device K32W1480 -if SWD -speed 4000 -autoconnect 1 -CommanderScript commands_script +``` + +## Debugging + +One option for debugging would be to use MCUXpresso IDE. + +- Drag-and-drop the zip file containing the NXP SDK in the "Installed SDKs" + tab: + +![Installed SDKs](../../../../platform/nxp/k32w/k32w1/doc/images/installed_sdks.jpg) + +- Import any demo application from the installed SDK: + +``` +Import SDK example(s).. -> choose a demo app (demo_apps -> hello_world) -> Finish +``` + +![Import demo](../../../../platform/nxp/k32w/k32w1/doc/images/import_demo.jpg) + +- Flash the previously imported demo application on the board: + +``` +Right click on the application (from Project Explorer) -> Debug as -> JLink/CMSIS-DAP +``` + +After this step, a debug configuration specific for the K32W1 board was created. +This debug configuration will be used later on for debugging the application +resulted after ot-nxp compilation. + +- Import Matter repo in MCUXpresso IDE as Makefile Project. Use _none_ as + _Toolchain for Indexer Settings_: + +``` +File -> Import -> C/C++ -> Existing Code as Makefile Project +``` + +![New Project](../../../../platform/nxp/k32w/k32w1/doc/images/new_project.jpg) + +- Replace the path of the existing demo application with the path of the K32W1 + application: + +``` +Run -> Debug Configurations... -> C/C++ Application +``` + +![Debug K32W1](../../../../platform/nxp/k32w/k32w1/doc/images/debug_k32w1.jpg) + +## OTA + +### Convert `srec` into `sb3` file + +The OTA image files must be encrypted using Over The Air Programming Tool +([OTAP](https://www.nxp.com/design/microcontrollers-developer-resources/connectivity-tool-suite:CONNECTIVITY-TOOL-SUITE?#downloads)). +Bootloader will load the new OTA image only if it detects that the file was +encrypted with the `OTAP` correct keys. + +`.srec` file is input for Over The air Programming (`OTAP`) application +(unencrypted) and it's converted to `.sb3` format (encrypted). + +In `OTAP` application + +- select OTA protocol => `OTAP` Matter +- Browse File +- follow default options (KW45/K32W148, Preserve NVM) +- image information: will update "Application Core (MCU)" - this will generate + the image only for the CM33 core +- keep other settings at default values + +### Convert `sb3` into `ota` file + +In order to build an OTA image, use NXP wrapper over the standard tool +`src/app/ota_image_tool.py`: + +- `scripts/tools/nxp/factory_data_generator/ota_image_tool.py` The tool can be + used to generate an OTA image with the following format: + `| OTA image header | TLV1 | TLV2 | ... | TLVn |` where each TLV is in the + form `|tag|length|value|` + +Note that "standard" TLV format is used. Matter TLV format is only used for +factory data TLV value. + +Please see more in the +[OTA image tool guide](https://github.com/project-chip/connectedhomeip/blob/master/scripts/tools/nxp/ota/README.md). + +Here is an example that generates an OTA image with application update TLV from +a `sb3` file: + +``` +./scripts/tools/nxp/ota/ota_image_tool.py create -v 0xDEAD -p 0xBEEF -vn 43033 -vs "1.0" -da sha256 --app-input-file ~/binaries/chip-k32w1-43033.sb3 ~/binaries/chip-k32w1-43033.ota + +``` + +A note regarding OTA image header version (`-vn` option). An application binary +has its own software version (given by +`CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION`, which can be overwritten). For +having a correct OTA process, the OTA header version should be the same as the +binary embedded software version. A user can set a custom software version in +the gn build args by setting `chip_software_version` to the wanted version. + +### Running OTA + +The OTA topology used for OTA testing is illustrated in the figure below. +Topology is similar with the one used for Matter Test Events. + +![OTA_TOPOLOGY](../../../../platform/nxp/k32w/k32w1/doc/images/ota_topology.JPG) + +The concept for OTA is the next one: + +- there is an OTA Provider Application that holds the OTA image. In our case, + this is a Linux application running on an Ubuntu based-system; +- the OTA Requestor functionality is embedded inside the Contact Sensor + Application. It will be used for requesting OTA blocks from the OTA + Provider; +- the controller (a linux application called chip-tool) will be used for + commissioning both the device and the OTA Provider App. The device will be + commissioned using the standard Matter flow (BLE + IEEE 802.15.4) while the + OTA Provider Application will be commissioned using the _onnetwork_ option + of chip-tool; +- during commissioning, each device is assigned a node id by the chip-tool + (can be specified manually by the user). Using the node id of the device and + of the contact sensor application, chip-tool triggers the OTA transfer by + invoking the _announce-ota-provider_ command - basically, the OTA Requestor + is informed of the node id of the OTA Provider Application. + +_Computer #1_ can be any system running an Ubuntu distribution. We recommand +using CSA official instructions from +[here](https://groups.csa-iot.org/wg/matter-csg/document/28566), where RPi 4 are +proposed. Also, CSA official instructions document point to the OS/Docker images +that should be used on the RPis. For compatibility reasons, we recommand +compiling chip-tool and OTA Provider applications with the same commit id that +was used for compiling the Contact Sensor Application. Also, please note that +there is a single controller (chip-tool) running on Computer #1 which is used +for commissioning both the device and the OTA Provider Application. If needed, +[these instructions](https://itsfoss.com/connect-wifi-terminal-ubuntu/) could be +used for connecting the RPis to WiFi. + +Build the Linux OTA provider application: + +``` +user@computer1:~/connectedhomeip$ : ./scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/ota-provider-app chip_config_network_layer_ble=false +``` + +Build Linux chip-tool: + +``` +user@computer1:~/connectedhomeip$ : ./scripts/examples/gn_build_example.sh examples/chip-tool out/chip-tool-app +``` + +Start the OTA Provider Application: + +``` +user@computer1:~/connectedhomeip$ : rm -rf /tmp/chip_* +user@computer1:~/connectedhomeip$ : ./out/ota-provider-app/chip-ota-provider-app -f chip-k32w1-43033.ota +``` + +Provision the OTA provider application and assign node id _1_. Also, grant ACL +entries to allow OTA requestors: + +``` +user@computer1:~/connectedhomeip$ : rm -rf /tmp/chip_* +user@computer1:~/connectedhomeip$ : ./out/chip-tool-app/chip-tool pairing onnetwork 1 20202021 +user@computer1:~/connectedhomeip$ : ./out/chip-tool-app/chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": null}]' 1 0 +``` + +Provision the device and assign node id _2_: + +``` +user@computer1:~/connectedhomeip$ : ./out/chip-tool-app/chip-tool pairing ble-thread 2 hex: 20202021 3840 +``` + +Start the OTA process: + +``` +user@computer1:~/connectedhomeip$ : ./out/chip-tool-app/chip-tool otasoftwareupdaterequestor announce-ota-provider 1 0 0 0 2 0 +``` + +## Low power + +The example also offers the possibility to run in low power mode. This means +that the board will go in deep sleep most of the time and the power consumption +will be very low. + +In order to build with low power support, the `chip_with_low_power=1` must be +provided to the build system. In this case, please note that the GN build +arguments `chip_openthread_ftd` and `chip_with_ot_cli` must be set to `false/0` +and `chip_logging` must be set to `false` to disable logging. + +In order to maintain a low power consumption, the LEDs showing the state of the +contact sensor and the internal state are disabled. Console logs can be used +instead. Also, please note that once the board is flashed with MCUXpresso the +debugger disconnects because the board enters low power. + +### Known issues + +- SRP cache on the openthread border router needs to flushed each time a new + commissioning process is attempted. For this, factory reset the device, then + execute _ot-ctl server disable_ followed by _ot-ctl server enable_. After + this step, the commissioning process of the device can start; +- Due to some MDNS issues, the commissioning of the OTA Provider Application + may fail. Please make sure that the SRP cache is disabled (_ot-ctl srp + server disable_) on the openthread border router while commissioning the OTA + Provider Application; +- No other Docker image should be running (e.g.: Docker image needed by Test + Harness) except the OTBR one. A docker image can be killed using the + command: + +``` +user@computer1:~/connectedhomeip$ : sudo docker kill $container_id +``` + +- In order to avoid MDNS issues, only one interface should be active at one + time. E.g.: if WiFi is used then disable the Ethernet interface and also + disable multicast on that interface: + +``` +user@computer1:~/connectedhomeip$ sudo ip link set dev eth0 down +user@computer1:~/connectedhomeip$ sudo ifconfig eth0 -multicast +``` + +- If OTBR Docker image is used, then the "-B" parameter should point to the + interface used for the backbone. + +- If Wi-Fi is used on a RPI4, then a 5Ghz network should be selected. + Otherwise, issues related to BLE-WiFi combo may appear. diff --git a/_sources/examples/contact-sensor-app/telink/README.md b/_sources/examples/contact-sensor-app/telink/README.md new file mode 100644 index 000000000000..c465190860bf --- /dev/null +++ b/_sources/examples/contact-sensor-app/telink/README.md @@ -0,0 +1,183 @@ +# Matter Telink Contact Sensor Example Application + +You can use this example as a reference for creating your own application. + +![Telink B91 EVK](http://wiki.telink-semi.cn/wiki/assets/Hardware/B91_Generic_Starter_Kit_Hardware_Guide/connection_chart.png) + +## Build and flash + +1. Run the Docker container: + + ```bash + $ docker run -it --rm -v $PWD:/host -w /host ghcr.io/project-chip/chip-build-telink:$(wget -q -O - https://raw.githubusercontent.com/project-chip/connectedhomeip/master/.github/workflows/examples-telink.yaml 2> /dev/null | grep chip-build-telink | awk -F: '{print $NF}') + ``` + + Compatible docker image version can be found in next file: + + ```bash + $ .github/workflows/examples-telink.yaml + ``` + +2. Activate the build environment: + + ```bash + $ source ./scripts/activate.sh -p all,telink + ``` + +3. In the example dir run (replace __ with your board name, for + example, `tlsr9518adk80d`, `tlsr9528a` or `tlsr9258a`): + + ```bash + $ west build -b + ``` + + Also use key `-DFLASH_SIZE`, if your board has memory size different from 2 + MB, for example, `-DFLASH_SIZE=1m` or `-DFLASH_SIZE=4m`: + + ```bash + $ west build -b tlsr9518adk80d -- -DFLASH_SIZE=4m + ``` + +4. Flash binary: + + ``` + $ west flash --erase + ``` + +## Usage + +### UART + +To get output from device, connect UART to following pins: + +| Name | Pin | +| :--: | :---------------------------- | +| RX | PB3 (pin 17 of J34 connector) | +| TX | PB2 (pin 16 of J34 connector) | +| GND | GND | + +### Buttons + +The following buttons are available on **tlsr9518adk80d** board: + +| Name | Function | Description | +| :------- | :--------------------- | :----------------------------------------------------------------------------------------------------- | +| Button 1 | Factory reset | Perform factory reset to forget currently commissioned Thread network and back to uncommissioned state | +| Button 2 | Toggle Contact State | Manually triggers the Contact Sensor State | +| Button 3 | NA | NA | +| Button 4 | Open commission window | The button is opening commissioning window to perform commissioning over BLE | + +### LEDs + +#### Indicate current state of Thread network + +**Red** LED indicates current state of Thread network. It is able to be in +following states: + +| State | Description | +| :-------------------------- | :--------------------------------------------------------------------------- | +| Blinks with short pulses | Device is not commissioned to Thread, Thread is disabled | +| Blinks with frequent pulses | Device is commissioned, Thread enabled. Device trying to JOIN thread network | +| Blinks with wide pulses | Device commissioned and joined to thread network as CHILD | + +#### Indicate identify of device + +**Green** LED used to identify the device. The LED starts blinking when the +Identify command of the Identify cluster is received. The command's argument can +be used to specify the the effect. It is able to be in following effects: + +| Effect | Description | +| :------------------------------ | :--------------------------------------------------------------------------- | +| Blinks (200 ms on/200 ms off) | Blink (`Clusters::Identify::EffectIdentifierEnum::kBlink`) | +| Breathe (during 1000 ms) | Breathe (`Clusters::Identify::EffectIdentifierEnum::kBreathe`) | +| Blinks (50 ms on/950 ms off) | Okay (`Clusters::Identify::EffectIdentifierEnum::kOkay`) | +| Blinks (1000 ms on/1000 ms off) | Channel Change ( `Clusters::Identify::EffectIdentifierEnum::kChannelChange`) | +| Blinks (950 ms on/50 ms off) | Finish ( `Clusters::Identify::EffectIdentifierEnum::kFinishEffect`) | +| LED off | Stop (`Clusters::Identify::EffectIdentifierEnum::kStopEffect`) | + +#### Indicate current state of Contact Sensor + +**White** LED shows current state of Contact Sensor + +### CHIP tool commands + +1. Build + [chip-tool cli](https://github.com/project-chip/connectedhomeip/blob/master/examples/chip-tool/README.md) + +2. Pair with device + + ``` + ${CHIP_TOOL_DIR}/chip-tool pairing ble-thread ${NODE_ID} hex:${DATASET} ${PIN_CODE} ${DISCRIMINATOR} + ``` + + Example: + + ``` + ./chip-tool pairing ble-thread 1234 hex:0e080000000000010000000300000f35060004001fffe0020811111111222222220708fd61f77bd3df233e051000112233445566778899aabbccddeeff030e4f70656e54687265616444656d6f010212340410445f2b5ca6f2a93a55ce570a70efeecb0c0402a0fff8 20202021 3840 + ``` + +### OTA with Linux OTA Provider + +OTA feature enabled by default only for ota-requestor-app example. To enable OTA +feature for another Telink example: + +- set CONFIG_CHIP_OTA_REQUESTOR=y in corresponding "prj.conf" configuration + file. + +After build application with enabled OTA feature, use next binary files: + +- zephyr.bin - main binary to flash PCB (Use at least 2MB PCB). +- zephyr-ota.bin - binary for OTA Provider + +All binaries has the same SW version. To test OTA “zephyr-ota.bin” should have +higher SW version than base SW. Set CONFIG_CHIP_DEVICE_SOFTWARE_VERSION=2 in +corresponding “prj.conf” configuration file. + +Usage of OTA: + +- Build the [Linux OTA Provider](https://github.com/project-chip/connectedhomeip/blob/master/examples/ota-provider-app/linux) + + ``` + ./scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/ota-provider-app chip_config_network_layer_ble=false + ``` + +- Run the Linux OTA Provider with OTA image. + + ``` + ./chip-ota-provider-app -f zephyr-ota.bin + ``` + +- Provision the Linux OTA Provider using chip-tool + + ``` + ./chip-tool pairing onnetwork ${OTA_PROVIDER_NODE_ID} 20202021 + ``` + + here: + + - \${OTA_PROVIDER_NODE_ID} is the node id of Linux OTA Provider + +- Configure the ACL of the ota-provider-app to allow access + + ``` + ./chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": null}]' ${OTA_PROVIDER_NODE_ID} 0 + ``` + + here: + + - \${OTA_PROVIDER_NODE_ID} is the node id of Linux OTA Provider + +- Use the chip-tool to announce the ota-provider-app to start the OTA process + + ``` + ./chip-tool otasoftwareupdaterequestor announce-otaprovider ${OTA_PROVIDER_NODE_ID} 0 0 0 ${DEVICE_NODE_ID} 0 + ``` + + here: + + - \${OTA_PROVIDER_NODE_ID} is the node id of Linux OTA Provider + - \${DEVICE_NODE_ID} is the node id of paired device + +Once the transfer is complete, OTA requestor sends ApplyUpdateRequest command to +OTA provider for applying the image. Device will restart on successful +application of OTA image. diff --git a/_sources/examples/darwin-framework-tool/README.md b/_sources/examples/darwin-framework-tool/README.md new file mode 100644 index 000000000000..863691adf273 --- /dev/null +++ b/_sources/examples/darwin-framework-tool/README.md @@ -0,0 +1,161 @@ +# Matter darwin-framework-tool + +An example application that uses Matter to send messages to a Matter server. + +IMPORTANT: Must have an Apple developer signed certificate. Information can be +found at [code-signing](https://developer.apple.com/support/code-signing/). + +--- + +- [Building the Example Application](#building-the-example-application) +- [Using the Client to Commission a Device](#using-the-client-to-commission-a-device) + +--- + +## Building the Example Application + +See [the build guide](../../guides/BUILDING.md#prerequisites) for general +background on build prerequisites. + +Building the example application is quite straightforward. + +``` +scripts/examples/gn_build_example.sh examples/darwin-framework-tool SOME-PATH/ +``` + +which puts the binary at `SOME-PATH/darwin-framework-tool`. + +## Using the Client to commission a device + +In order to send commands to a device, it must be commissioned with the client. +darwin-framework-tool currently only supports commissioning and remembering one +device at a time. The configuration state is stored in +`/tmp/chip_tool_config.ini`; deleting this and other `.ini` files in `/tmp` can +sometimes resolve issues due to stale configuration. + +#### Commission a device + +To initiate a client commissioning request to a device, run the built executable +and choose the pairing mode. + +#### Pair a device over IP + +The command below will pair devices with the provided IP, discriminator and +setup code. + + $ darwin-framework-tool pairing ethernet {NODE_ID_TO_ASSIGN} 20202021 3840 {IP_ADDRESS} + +In this case, the device will be assigned node id `${NODE_ID_TO_ASSIGN}` (which +must be a decimal number or a 0x-prefixed hex number). + +### Forget the currently-commissioned device + + $ darwin-framework-tool pairing unpair + +## Using the Client to Send Matter Commands + +To use the Client to send Matter commands, run the built executable and pass it +the target cluster name, the target command name as well as an endpoint id. + +The endpoint id must be between 1 and 240. + + $ darwin-framework-tool onoff on 1 + +The client will send a single command packet and then exit. + +### How to get the list of supported clusters + +To get the list of supported clusters, run the built executable without any +arguments. + + $ darwin-framework-tool + +Example output: + +```bash +Usage: + ./darwin-framework-tool cluster_name command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Clusters: | + +-------------------------------------------------------------------------------------+ + | * basic | + | * colorcontrol | + | * doorlock | + | * groups | + | * iaszone | + | * identify | + | * levelcontrol | + | * onoff | + | * pairing | + | * payload | + | * scenes | + | * temperaturemeasurement | + +-------------------------------------------------------------------------------------+ +``` + +### How to get the list of supported commands for a specific cluster + +To get the list of commands for a specific cluster, run the built executable +with the target cluster name. + + $ darwin-framework-tool onoff + +### How to get the list of supported attributes for a specific cluster + +To the the list of attributes for a specific cluster, run the built executable +with the target cluster name and the `read` command name. + + $ darwin-framework-tool onoff read + +### How to get the list of parameters for a command + +To get the list of parameters for a specific command, run the built executable +with the target cluster name and the target command name + + $ darwin-framework-tool onoff on + +## Using Interactive mode + +To start the interactive mode run the following command: + + $ darwin-framework-tool interactive start + +Once in interactive mode, 'help' will display commands available + +## Using the OTA Software Update app + +OTA SW app will only work in interactive mode. In interactive mode there will be +an additional command 'otasoftwareupdateapp'. Running the following command in +interactive will display available commands. + + $ otasoftwareupdateapp + +The following json is an example of a list of candidates to set in interactive +mode with `otasoftwareupdateapp candidate-file-path`: + +```json +{ + "deviceSoftwareVersionModel": [ + { + "vendorId": 65521, + "productId": 32769, + "softwareVersion": 10, + "softwareVersionString": "1.0.0", + "cDVersionNumber": 18, + "softwareVersionValid": true, + "minApplicableSoftwareVersion": 0, + "maxApplicableSoftwareVersion": 100, + "otaURL": "/Users/josh/Desktop/OTACandidates/ota_v10.bin" + } + ] +} +``` + +darwin-framework-tool allows to set the consent status on the Provider side with +the following command: + + $ otasoftwareupdateapp set-consent-status [granted, obtaining, denied] + +By default, the consent will be set to unknown and the requestor will have to +consent. If the requestor cannot consent, the update will be denied. diff --git a/_sources/examples/discussion/PID_allocation_for_example_apps.md b/_sources/examples/discussion/PID_allocation_for_example_apps.md new file mode 100644 index 000000000000..2ebb169e60f0 --- /dev/null +++ b/_sources/examples/discussion/PID_allocation_for_example_apps.md @@ -0,0 +1,40 @@ +--- +orphan: true +--- + +# PID allocation for example apps + +Unless specifically overridden by the platform, example apps in this SDK use the +Example credentials implementation in `DeviceAttestationCredsExample.cpp`. + +The SDK holds example certificates for VID `0xFFF1` and any PID in +`0x8000-0x801F`. The device VID and PID supplied by the basic information +cluster must correspond to the VID/PID given in the certificate for the device +to pass verification. + +Certificates are selected using the value in +CHIP_DEVICE_CONFIG_DEVICE_PRODUCT_ID. The vendor ID for every example app is the +same because they are all signed by the same PAI (vendor id `0xFFF1`). + +In order to allow some differentiation between the various example apps, each +app is assigned a PID from the list below: + +| App | PID | +| ----------------------- | -------- | +| All Clusters | `0x8001` | +| Bridge | `0x8002` | +| Door Lock | `0x8003` | +| Light switch | `0x8004` | +| Lighting | `0x8005` | +| Lock | `0x8006` | +| OTA provider | `0x8007` | +| OTA requestor | `0x8008` | +| Persistent Storage | `0x8009` | +| Pigweed | `0x800B` | +| Pump | `0x800A` | +| Pump Controller | `0x8011` | +| Shell | `0x8012` | +| Temperature measurement | `0x800D` | +| Thermostat | `0x800E` | +| TV | `0x800F` | +| Window | `0x8010` | diff --git a/_sources/examples/dishwasher-app/linux/README.md b/_sources/examples/dishwasher-app/linux/README.md new file mode 100644 index 000000000000..e6c2469a94b3 --- /dev/null +++ b/_sources/examples/dishwasher-app/linux/README.md @@ -0,0 +1,146 @@ +# Matter Linux Lighting Example + +An example showing the use of Matter on the Linux. The document will describe +how to build and run Matter Linux Lighting Example on Raspberry Pi. This doc is +tested on **Ubuntu for Raspberry Pi Server 20.04 LTS (aarch64)** and **Ubuntu +for Raspberry Pi Desktop 20.10 (aarch64)** + +To cross-compile this example on x64 host and run on **NXP i.MX 8M Mini** +**EVK**, see the associated +[README document](../../../guides/nxp/nxp_imx8m_linux_examples.md) for +details. + +
    + +- [Matter Linux Lighting Example](#matter-linux-lighting-example) + - [Building](#building) + - [Commandline Arguments](#commandline-arguments) + - [Running the Complete Example on Raspberry Pi 4](#running-the-complete-example-on-raspberry-pi-4) + - [Running RPC console](#running-rpc-console) + - [Device Tracing](#device-tracing) + +
    + +## Building + +- Install tool chain + + $ sudo apt-get install git gcc g++ python pkg-config libssl-dev libdbus-1-dev libglib2.0-dev ninja-build python3-venv python3-dev unzip + +- Build the example application: + + $ cd ~/connectedhomeip/examples/lighting-app/linux + $ git submodule update --init + $ source third_party/connectedhomeip/scripts/activate.sh + $ gn gen out/debug + $ ninja -C out/debug + +- To delete generated executable, libraries and object files use: + + $ cd ~/connectedhomeip/examples/lighting-app/linux + $ rm -rf out/ + +- Build the example with pigweed RPC + + $ cd ~/connectedhomeip/examples/lighting-app/linux + $ git submodule update --init + $ source third_party/connectedhomeip/scripts/activate.sh + $ gn gen out/debug --args='import("//with_pw_rpc.gni")' + $ ninja -C out/debug + +## Commandline arguments + +- `--wifi` + + Enables WiFi management feature. Required for WiFi commissioning. + +- `--thread` + + Enables Thread management feature, requires ot-br-posix dbus daemon running. + Required for Thread commissioning. + +- `--ble-device ` + + Use specific bluetooth interface for BLE advertisement and connections. + + `interface id`: the number after `hci` when listing BLE interfaces by + `hciconfig` command, for example, `--ble-device 1` means using `hci1` + interface. Default: `0`. + +## Running the Complete Example on Raspberry Pi 4 + +> If you want to test Echo protocol, please enable Echo handler +> +> gn gen out/debug --args='chip_app_use_echo=true' +> ninja -C out/debug + +- Prerequisites + + 1. A Raspberry Pi 4 board + 2. A USB Bluetooth Dongle, Ubuntu desktop will send Bluetooth advertisement, + which will block Matter from connecting via BLE. On Ubuntu server, you + need to install `pi-bluetooth` via APT. + 3. Ubuntu 20.04 or newer image for ARM64 platform. + +- Building + + Follow [Building](#building) section of this document. + +- Running + + - [Optional] Plug USB Bluetooth dongle + + - Plug USB Bluetooth dongle and find its bluetooth device number. The + number after `hci` is the bluetooth device number, `1` in this + example. + + $ hciconfig + hci1: Type: Primary Bus: USB + BD Address: 00:1A:7D:AA:BB:CC ACL MTU: 310:10 SCO MTU: 64:8 + UP RUNNING PSCAN ISCAN + RX bytes:20942 acl:1023 sco:0 events:1140 errors:0 + TX bytes:16559 acl:1011 sco:0 commands:121 errors:0 + + hci0: Type: Primary Bus: UART + BD Address: B8:27:EB:AA:BB:CC ACL MTU: 1021:8 SCO MTU: 64:1 + UP RUNNING PSCAN ISCAN + RX bytes:8609495 acl:14 sco:0 events:217484 errors:0 + TX bytes:92185 acl:20 sco:0 commands:5259 errors:0 + + - Run Linux Lighting Example App + + $ cd ~/connectedhomeip/examples/lighting-app/linux + $ sudo out/debug/chip-lighting-app --ble-device [bluetooth device number] + # In this example, the device we want to use is hci1 + $ sudo out/debug/chip-lighting-app --ble-device 1 + + - Test the device using ChipDeviceController on your laptop / + workstation etc. + +## Running RPC Console + +- As part of building the example with RPCs enabled the chip_rpc python + interactive console is installed into your venv. The python wheel files are + also created in the output folder: out/debug/chip_rpc_console_wheels. To + install the wheel files without rebuilding: + `pip3 install out/debug/chip_rpc_console_wheels/*.whl` + +- To use the chip-rpc console after it has been installed run: + `chip-console -s localhost:33000 -o //pw_log.out` + +- Then you can Get and Set the light using the RPCs: + `rpcs.chip.rpc.Lighting.Get()` + + `rpcs.chip.rpc.Lighting.Set(on=True, level=128, color=protos.chip.rpc.LightingColor(hue=5, saturation=5))` + +## Device Tracing + +Device tracing is available to analyze the device performance. To turn on +tracing, build with RPC enabled. See [Building with RPC enabled](#building). + +Obtain tracing json file. + +``` + $ ./{PIGWEED_REPO}/pw_trace_tokenized/py/pw_trace_tokenized/get_trace.py -s localhost:33000 \ + -o {OUTPUT_FILE} -t {ELF_FILE} {PIGWEED_REPO}/pw_trace_tokenized/pw_trace_protos/trace_rpc.proto +``` diff --git a/_sources/examples/energy-management-app/esp32/README.md b/_sources/examples/energy-management-app/esp32/README.md new file mode 100644 index 000000000000..4c95da2a74fd --- /dev/null +++ b/_sources/examples/energy-management-app/esp32/README.md @@ -0,0 +1,49 @@ +# Matter ESP32 Energy Management Example + +This example demonstrates the Matter Electric Vehicle Supply Equipment +application on ESP platforms. + +Please +[setup ESP-IDF and CHIP Environment](../../../guides/esp32/setup_idf_chip.md) +and refer +[building and commissioning](../../../guides/esp32/build_app_and_commission.md) +guides to get started. + +### Enabling ESP-Insights: + +- Before building the app, enable the option: ESP_INSIGHTS_ENABLED through + menuconfig. + +- Create a file named insights_auth_key.txt in the main directory of the + example. + +- Follow the steps + present[here](https://github.com/espressif/esp-insights/blob/main/examples/README.md#set-up-esp-insights-account) + to set up an insights_account and the auth key created while setting it up + will be used in the example. + +- Download the auth key and copy Auth Key to the example + +``` +cp /path/to/auth/key.txt path/to/connectedhomeip/examples/energy-management-app/esp32/main/insights_auth_key.txt +``` + +--- + +- [Cluster Control](#cluster-control) +- [Matter OTA guide](../../../guides/esp32/ota.md) + +--- + +### Cluster Control + +- After successful commissioning, use the Energy Electric Vehicle Supply + Equipment cluster command to disable/enable charging and discharging. + +``` + $./out/debug/chip-tool energyevse disable 1 +``` + +``` + $ ./out/debug/chip-tool energyevse enable-charging 0xFFFFFFFF 6000 32000 1 --timedInteractionTimeoutMs
  • granted: Status field in the first QueryImageResponse is set to updateAvailable
  • denied: Status field in the first QueryImageResponse is set to updateNotAvailable
  • deferred: Status field in the first QueryImageResponse is set to busy | +| -x, --ignoreQueryImage \ | The number of times to ignore the QueryImage Command and not send a response | +| -y, --ignoreApplyUpdate \ | The number of times to ignore the ApplyUpdate Request and not send a response | +| -P, --pollInterval | Poll interval for the BDX transfer. | + +**Using `--filepath` and `--otaImageList`** + +- The two options cannot be supplied together +- At least one option must be supplied +- If `--filepath` is supplied, the application will automatically serve that + file to the OTA Requestor +- If `--otaImageList` is supplied, the application will parse the JSON file + and extract all required data. The most recent/valid software version will + be selected and the corresponding OTA file will be sent to the OTA Requestor +- The SoftwareVersion and SoftwareVersionString sent in the QueryImageResponse + is derived from the OTA image header. Please note that if the version in the + `--otaImageList` JSON file does not match that in the image header, the + application will terminate. + +An example of the `--otaImageList` file contents: + +``` +{ "foo": 1, // ignored by parser + "deviceSoftwareVersionModel": + [ + { "vendorId": 1, "productId": 1, "softwareVersion": 10, "softwareVersionString": "1.0.0", "cDVersionNumber": 18, "softwareVersionValid": true, "minApplicableSoftwareVersion": 0, "maxApplicableSoftwareVersion": 100, "otaURL": "/tmp/ota_v10.bin" }, + { "vendorId": 1, "productId": 1, "softwareVersion": 20, "softwareVersionString": "1.0.1", "cDVersionNumber": 18, "softwareVersionValid": false, "minApplicableSoftwareVersion": 0, "maxApplicableSoftwareVersion": 100, "otaURL": "/tmp/ota_v20.bin" }, + { "vendorId": 1, "productId": 1, "softwareVersion": 30, "softwareVersionString": "1.0.2", "cDVersionNumber": 18, "softwareVersionValid": true, "minApplicableSoftwareVersion": 0, "maxApplicableSoftwareVersion": 100, "otaURL": "/tmp/ota_v30.bin" }, + { "vendorId": 1, "productId": 1, "softwareVersion": 40, "softwareVersionString": "1.1.0", "cDVersionNumber": 18, "softwareVersionValid": true, "minApplicableSoftwareVersion": 0, "maxApplicableSoftwareVersion": 100, "otaURL": "/tmp/ota_v40.bin" }, + { "vendorId": 1, "productId": 1, "softwareVersion": 50, "softwareVersionString": "1.1.1", "cDVersionNumber": 18, "softwareVersionValid": false, "minApplicableSoftwareVersion": 0, "maxApplicableSoftwareVersion": 100, "otaURL": "/tmp/ota_v50.bin" } + ] +} +``` + +## Software Image Header + +All Matter software images must contain a header as defined in section 11.21.1 +of the specification. The +[ota_image_tool](https://github.com/project-chip/connectedhomeip/blob/master/src/app/ota_image_tool.py) +is available for generating the required header on a software image. + +All images supplied to the OTA Provider application (via `--filepath` or +`--otaImageList`) must contain the software image header. The OTA Provider +application will use the software version specified in the header to set the +`SoftwareVersion` field of the QueryImageResponse. For instance, if the image +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) +for information on building an OTA Requestor application with a specific +software version. + +## Access Control Requirements + +Commissioner or Administrator SHOULD install necessary ACL entries at +commissioning time or later to enable processing of QueryImage commands from OTA +Requestors on their fabric, otherwise that OTA Provider will not be usable by +OTA Requestors. + +Since the ACL attribute contains a list of ACL entries, writing of the attribute +should not just contain the values for the new entry. Any existing entries +should be read and included as part of the write. Below is an example of how to +write the ACL attribute with two entries: + +``` +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 +``` + +- Entry 1: This is the original entry created as part of commissioning which + grants administer privilege to the node ID 112233 (default controller node + ID) for all clusters on every endpoint +- Entry 2: This is the new entry being added which grants operate privileges + to all nodes for the OTA Provider cluster (0x0029) on every endpoint + +In the example above, the provider is on fabric index 1 with provider node ID +being `0xDEADBEEF` on endpoint 0. + +## Current Limitations + +- Synchronous BDX transfer only +- Does not check VID/PID +- Only one transfer at a time (does not check incoming `UpdateTokens`) diff --git a/_sources/examples/ota-requestor-app/ameba/README.md b/_sources/examples/ota-requestor-app/ameba/README.md new file mode 100644 index 000000000000..60d75e37c739 --- /dev/null +++ b/_sources/examples/ota-requestor-app/ameba/README.md @@ -0,0 +1,71 @@ +# CHIP Ameba OTA Requestor Example + +A prototype application that demonstrates OTA Requestor capabilities. + +## Building the Example Application + +- Pull docker image: + + $ docker pull ghcr.io/project-chip/chip-build-ameba:47 + +- Run docker container: + + $ docker run -it -v ${CHIP_DIR}:/root/chip ghcr.io/project-chip/chip-build-ameba:47 + +- Setup build environment: + + $ source ./scripts/bootstrap.sh + +- To build the demo application: + + $ ./scripts/build/build_examples.py --target ameba-amebad-ota-requestor build + + The output image files are stored in + `out/ameba-amebad-ota-requestor/asdk/image` folder. + + The bootloader image files are stored in + `out/ameba-amebad-ota-requestor/asdk/bootloader` folder. + +- After building the application, **Ameba Image Tool** is used to flash it to + Ameba board. + +1. Connect your device via USB and open Ameba Image Tool. +2. Select correct serial port and set baudrate as **115200**. +3. Browse and add the corresponding image files in the Flash Download list to + the correct locations +4. Click **Download** button. + +## Testing the Example Application + +1. Commission Ameba (ota-requestor-app) using chip-tool + + $ ./chip-tool pairing ble-wifi 1 20202021 3840 + +2. Launch the linux [ota-provider-app](https://github.com/project-chip/connectedhomeip/blob/master/examples/ota-provider-app/linux) and + provide the SW_IMAGE_FILE + + $ ./chip-ota-provider-app -f ${SW_IMAGE_FILE} + +3. Commission the ota-provider-app using + [chip-tool](https://github.com/project-chip/connectedhomeip/tree/master/examples/chip-tool) + + $ ./chip-tool pairing onnetwork 2 20202021 + +4. Write the Default OTA providers into Ameba + + $ ./chip-tool otasoftwareupdaterequestor write default-otaproviders '[{"fabricIndex": 1, "providerNodeID": 2, "endpoint": 0}]' 1 0 + +5. Configure the ACL of the ota-provider-app to allow access for Ameba + + $ ./chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": [{"cluster": 41, "endpoint": null, "deviceType": null}]}]' 1235 0 + +6. Use the chip-tool to announce the ota-provider-app to start the OTA process + + $ ./chip-tool otasoftwareupdaterequestor announce-otaprovider 1 0 0 0 2 0 + +7. The OTA process should include downloading the image, verification of image + header, erasing upgraded flash partition, writing to flash and checksum + verification. + +8) Once OTA signature is updated, Ameba will reboot into the new image after 10 + seconds countdown. diff --git a/_sources/examples/ota-requestor-app/asr/README.md b/_sources/examples/ota-requestor-app/asr/README.md new file mode 100644 index 000000000000..f6917cc9eb28 --- /dev/null +++ b/_sources/examples/ota-requestor-app/asr/README.md @@ -0,0 +1,57 @@ +# Matter ASR OTA Requestor Example + +This example demonstrates the Matter OTA Requestor application on ASR platform. + +--- + +- [Matter ASR OTA Requestor Example](#matter-asr-ota-requestor-example) + - [Building and Commissioning](#building-and-commissioning) + - [Testing the example](#testing-the-example) + +--- + +## Building and Commissioning + +Please refer +[Building and Commissioning](../../../guides/asr_getting_started_guide.md#building-the-example-application) +guides to get started + +``` +./scripts/build/build_examples.py --target asr-$ASR_BOARD-ota-requestor build +``` + +## Testing the example + +- After building a application, `*ota.bin` will generated automatically in the + output directory. + +- Use + [ota_image_tool](https://github.com/project-chip/connectedhomeip/blob/master/src/app/ota_image_tool.py) + to generate the Matter OTA image. This tool can be used as follows, make + sure the softwareVersion parameter must be greater than the + `CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION` parameter set in the + application's CHIPProjectConfig.h file. + + ``` + ./src/app/ota_image_tool.py create -v -p -vn 2 -vs "2.0" -da sha256 application_ota.bin matter_firmware_ota.bin + ``` + +- Run the Linux OTA Provider with OTA image. + ``` + ./chip-ota-provider-app -f matter_firmware_ota.bin + ``` +- OTA Provider commissioning in another Linux terminal. + ``` + ./chip-tool pairing onnetwork 1 20202021 + ``` +- After OTA Provider commissioning is successful, use `chip-tool` to write ACL + for OTA Provider. + ``` + ./chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null },{"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": null }]' 1 0 + ``` +- Commission ota requestor device with node-id `OTA REQUESTOR APP NODE ID` +- After OTA Requestor commissioning is successful, use `chip-tool` to inform + OTA Provider to send OTA image to OTA Requestor. + ``` + ./chip-tool otasoftwareupdaterequestor announce-otaprovider 1 0 0 0 0 + ``` diff --git a/_sources/examples/ota-requestor-app/esp32/README.md b/_sources/examples/ota-requestor-app/esp32/README.md new file mode 100644 index 000000000000..7ee433bffbb1 --- /dev/null +++ b/_sources/examples/ota-requestor-app/esp32/README.md @@ -0,0 +1,57 @@ +# CHIP ESP32 OTA Requestor Example + +A prototype application that demonstrates OTA Requestor capabilities. + +Please +[setup ESP-IDF and CHIP Environment](../../../guides/esp32/setup_idf_chip.md) +and refer +[building and commissioning](../../../guides/esp32/build_app_and_commission.md) +guides to get started. + +--- + +- [Prerequisite](#prerequisite) +- [Query for an OTA Image](#query-for-an-ota-image) +- [ESP32 OTA Requestor with Linux OTA Provider](#esp32-ota-requestor-with-linux-ota-provider) +- [RPC console and Device Tracing](../../../guides/esp32/rpc_console.md) + +--- + +## Prerequisite + +Before moving ahead, make sure you have +[OTA Provider](https://github.com/project-chip/connectedhomeip/blob/master/examples/ota-provider-app/esp32) is commissioned and running. + +### Query for an OTA Image + +After commissioning is successful, announce OTA provider's presence using +chip-tool. On receiving this command OTA requestor will query for OTA image. + +``` +./out/debug/chip-tool otasoftwareupdaterequestor announce-otaprovider 0 0 0 0 +``` + +Once the transfer is complete, OTA requestor sends ApplyUpdateRequest command to +OTA provider for applying the image. Device will restart on successful +application of OTA image. + +### ESP32 OTA Requestor with Linux OTA Provider + +- Build the [Linux OTA Provider](../../ota-provider-app/linux/README.md) +- Run the Linux OTA Provider with OTA image. + +``` +./out/debug/chip-ota-provider-app -f hello-world.bin +``` + +- Provision the Linux OTA Provider using chip-tool + +``` +./out/debug/chip-tool pairing onnetwork 12345 20202021 +``` + +### Note + +While trying out example ota-requestor-app bump the software version from +`CMakeList.txt` and not from `idf.py menuconfig`. And software version of the +image which is being ota should be greater than current software version. diff --git a/_sources/examples/ota-requestor-app/genio/README.md b/_sources/examples/ota-requestor-app/genio/README.md new file mode 100644 index 000000000000..50bc08f2b591 --- /dev/null +++ b/_sources/examples/ota-requestor-app/genio/README.md @@ -0,0 +1,106 @@ +# Matter `Genio` Lighting Example + +An example showing the use of Matter on the MediaTek `Genio` MT793X. + +
    + +- [Matter Genio Lighting Example](#matter-genio-lighting-example) + - [Introduction](#introduction) + - [Building](#building) + - [Flashing the Application](#flashing-the-application) + - [Running the Complete Example](#running-the-complete-example) + - [Notes](#notes) + +
    + +## Introduction + +The `Genio` (MT793X) lighting example provides a baseline demonstration of a +Light control device, built using Matter and the MediaTek `Genio` SDK. It can be +controlled by a Chip controller over Wi-Fi network. + +The `Genio` device can be commissioned over Bluetooth Low Energy where the +device and the Chip controller will exchange security information with the +Rendez-vous procedure. Network credentials are then provided to the `Genio` +device which will then join the network. + +The lighting example is intended to serve both as a means to explore the +workings of Matter as well as a template for creating real products based on the +MediaTek platform. + +## Building + +- Following the Linux related descriptions in + [Build Matter](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/BUILDING.md) + to prepare the build environment. + +- Supported hardware: + + `Genio` 130A (MT7931) board: + + - `EK-AI7931LD KIT` + +* Build the example application: + + `cd ~/connectedhomeip` + `./scripts/examples/gn_genio_example.sh ./examples/lighting-app/genio` `./out/lighting-app` + +- To delete generated executable, libraries and object files use: + + `$ cd ~/connectedhomeip` + `$ rm -rf ./out/` + + OR use GN/Ninja directly + + `$ cd ~/connectedhomeip/examples/lighting-app/genio` + `$ git submodule update --init` + `$ source third_party/connectedhomeip/scripts/activate.sh` + `$ gn gen out/debug` + `$ ninja -C out/debug` + +- To delete generated executable, libraries and object files use: + + `$ cd ~/connectedhomeip/examples/lighting-app/genio` + `$ rm -rf out/` + +## Flashing the Application + +- Copy the GUI based + [Flash Tool](https://github.com/MediaTek-Labs/genio-matter-bsp/tree/main/flash_tool/FlashBurningTool_V2.83). + from the Linux Host that the example was build to a Windows PC. + + Flash Tool can be found in this source tree under this directory + + `third_party/mt793x_sdk/filogic/flash_tool` + +- On the Windows PC, run the Flash Tool + + 1. Select the scatter.ini file in the `./out/lighting-app` directory. + 2. Follow the instruction that comes with `EK-AI7931LD KIT` to switch the + kit to download mode. + 3. Click `Download` on FLASH TOOL. + +## Running the Complete Example + +- You can provision and control the Chip device using the python controller, + Chip tool standalone, Android or iOS app + + [CHIP + Tool]](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/chip_tool_guide.md) + + Here is an example with the CHIP Tool controller: + + ``` + chiptool- pairing ble-wifi 1234 my-ap myappassword 20202021 3840 + + chiptool onoff on 1 1 + + chiptool onoff off 1 1 + ``` + +### Notes + +- Depending on your network settings your router might not provide native ipv6 + addresses to your devices (Border router / PC). If this is the case, you + need to add a static ipv6 addresses on both device and then an ipv6 route to + the border router on your PC diff --git a/_sources/examples/ota-requestor-app/infineon/cyw30739/README.md b/_sources/examples/ota-requestor-app/infineon/cyw30739/README.md new file mode 100644 index 000000000000..9b066c329c53 --- /dev/null +++ b/_sources/examples/ota-requestor-app/infineon/cyw30739/README.md @@ -0,0 +1,139 @@ +# Matter CYW30739 OTA Requestor Example + +An example showing the use of the Matter OTA Requestor functionality on the +Infineon CYW30739 platform. + +--- + +## Table of Contents + +- [CHIP CYW30739 OTA Requestor Example](#matter-cyw30739-ota-requestor-example) + - [Introduction](#introduction) + - [Building](#building) + - [Flashing the Application](#flashing-the-application) + - [Running the Complete Example](#running-the-complete-example) + +--- + +## Introduction + +The CYW30739 OTA Requestor example provides a baseline demonstration the Matter +OTA Requestor functionality built with the Infineon Modustoolbox SDK. It can be +controlled by a Matter controller over Thread network. + +The CYW30739 device can be commissioned over Bluetooth Low Energy where the +device and the Matter controller will exchange security information with the +Rendez-vous procedure. Target Thread Network information including the active +dataset and CASE credentials are then provided. + +## Building + +- Build the example application: + + ```bash + $ cd ~/connectedhomeip + $ git submodule update --init + $ ./scripts/examples/gn_build_example.sh examples/ota-requestor-app/infineon/cyw30739 out/ota-requestor-app + ``` + +- To delete generated executable, libraries and object files use: + + ```bash + $ cd ~/connectedhomeip + $ rm -rf ./out/ + ``` + +- OR use GN/Ninja directly + + ```bash + $ cd ~/connectedhomeip/examples/ota-requestor-app/infineon/cyw30739 + $ git submodule update --init + $ source third_party/connectedhomeip/scripts/activate.sh + $ gn gen out/debug + $ ninja -C out/debug + ``` + +- To delete generated executable, libraries and object files use: + + ```bash + $ cd ~/connectedhomeip/examples/ota-requestor-app/infineon/cyw30739 + $ rm -rf out/ + ``` + +## Building Options + +### DAC / DAC Key / PAI Certificate / Certificate Declaration + +Infineon CYW30739 examples use test certifications, keys, and CD by default. For +a production build, manufacturers can provision certifications, keys, and CD by +the following arguments: + +- `matter_dac`, `matter_dac_key`, `matter_pai`, `matter_cd` + + ```bash + $ ./scripts/examples/gn_build_example.sh examples/lighting-app/infineon/cyw30739 out/lighting-app \ + 'matter_dac="/path/to/dac.der"' \ + 'matter_dac_key="/path/to/dac_key.der"' \ + 'matter_pai="/path/to/pai.der"' \ + 'matter_cd="/path/to/cd.der"' + ``` + +## Flashing the Application + +### Enter Recovery Mode + +Put the CYW30739 in to the recovery mode before running the flash script. + +1. Press and hold the `RECOVERY` button on the board. +2. Press and hold the `RESET` button on the board. +3. Release the `RESET` button. +4. After one second, release the `RECOVERY` button. + +### Run Flash Script + +- On the command line: + + ```bash + $ cd ~/connectedhomeip/examples/ota-requestor-app/infineon/cyw30739 + $ python3 out/debug/chip-cyw30739-ota-requestor-example.flash.py + ``` + +## Running the Complete Example + +- It is assumed here that you already have an OpenThread border router + configured and running. If not see the following guide + [Openthread_border_router](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/openthread_border_router_pi.md) + for more information on how to setup a border router on a raspberryPi. + + - Get the active dataset hex for the chip-tool. + ```bash + ot-ctl dataset active -x + ``` + +- You can provision and control the Chip device using the python controller, + Chip tool standalone, Android or iOS app + + [Chip tool](https://github.com/project-chip/connectedhomeip/blob/master/examples/chip-tool/README.md) + + Here is an example with the chip tool: + + - Start a Linux OTA Provider. + + ```bash + # Start the OTA provider server with an OTA binary file + chip-ota-provider-app -f + ``` + + - Setup the CYW30739 OTA Requestor the the Linux OTA Provider by the + controller. + + ```bash + # Pair the OTA Requestor + chip-tool pairing ble-thread 1234 hex:0e080000000000000000000300000b35060004001fffe00208dead00beef00cafe0708fddead00beef000005108e11d8ea8ffaa875713699f59e8807e0030a4f70656e5468726561640102c2980410edc641eb63b100b87e90a9980959befc0c0402a0fff8 20202021 3840 + + # Pair the OTA Provider + chip-tool pairing onnetwork-vendor 4321 20202021 9050 + + # Announce the OTA provider to the requestor + chip-tool otasoftwareupdaterequestor announce-otaprovider 4321 9 0 0 1234 0 + ``` diff --git a/_sources/examples/ota-requestor-app/linux/README.md b/_sources/examples/ota-requestor-app/linux/README.md new file mode 100644 index 000000000000..ef422077dc5c --- /dev/null +++ b/_sources/examples/ota-requestor-app/linux/README.md @@ -0,0 +1,428 @@ +# ota-requestor-app (Linux) + +This is a reference application that is both a server for the OTA Requestor +Cluster, as well as a client of the OTA Provider Cluster. It can initiate a +software update with a given OTA Provider node, and download a file. + +## Build + +Suggest doing the following: + +``` +scripts/examples/gn_build_example.sh examples/ota-requestor-app/linux out/debug chip_config_network_layer_ble=false +``` + +## Usage + +In addition to the general options available to all Linux applications, the +following command line options are available for the OTA Requestor application. +Note that these options are for testing purposes. + +| Command Line Option | Description | +| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| -a, --autoApplyImage | If supplied, apply the image immediately after download. Otherwise, the OTA update is complete after image download. | +| -c, --requestorCanConsent \ | Value for the RequestorCanConsent field in the QueryImage command. If not supplied, the value is determined by the driver. | +| -d, --disableNotifyUpdateApplied | If supplied, disable sending of the NotifyUpdateApplied command. Otherwise, after successfully loading into the updated image, send the NotifyUpdateApplied command. | +| -f, --otaDownloadPath \ | If supplied, the OTA image is downloaded to the given fully-qualified file-path. Otherwise, the default location for the downloaded image is at /tmp/test.bin | +| -p, --periodicQueryTimeout \
  • granted: Authorize OTA requestor to download an OTA image
  • denied: Forbid OTA requestor to download an OTA image
  • deferred: Defer obtaining user consent | +| -w, --watchdogTimeout \