Skip to content

Commit

Permalink
Documentation: Add MD version of webinar
Browse files Browse the repository at this point in the history
Adds a slightly cleaned up version of the quick start guide
webinar section 1 as a quick start guide. The old quick start
is quite out of date, we should consider removing that and using
this as a replacement.

NOTE: Still need to hook in the indexes, and determin what to do
with the current quick start file (move this and replace?)
  • Loading branch information
cecille committed May 21, 2024
1 parent 443bb9c commit 3009427
Showing 1 changed file with 123 additions and 0 deletions.
123 changes: 123 additions & 0 deletions docs/getting_started/first_example.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
# An SDK example

The SDK provides a number of example devices and controllers that can be used to
familiarize yourself with the SDK and the Matter ecosystem.

## Example Devices

The example devices (occasionally referred to as "apps") are located in the
[examples](../../examples/) directory. The examples often implement one
particular device type. Some have implementations for various platforms.

The linux platform examples are provided as examples, and are used in the CI.
These can be used for preliminary testing.

The all-clusters-app is used by the QA team for testing. This app implements
nearly all the available clusters and does not conform to a specific device
type. This app is not a good starting place for product development.

## Example Controllers

The SDK has two example controllers that can be used to interact with devices
for testing.

[chip-tool](../../examples/chip-tool/) is a C++ command line controller with an
interactive shell. More information on chip-tool can be found in the
[chip-tool guide](../guides/chip_tool_guide.md).

[chip-repl](../../src/controller/python/chip-repl.py) is a shell for the python
controller. The chip-repl is part of the python controller framework, often used
for testing. More information about the python controller can be found in the
[python testing](../testing/python.md) documentation.

## Building your first demo app (lighting)

The examples directory contains a set of apps using an example device
composition \.zap file. (For more information about device composition and zap,
see [ZAP documentation](../getting_started/zap.md)).

This quick start guide will walk you through

- Building an app (lighting app) for the host platform
- Interacting with the app using chip\-tool \(controller\)

### Building the lighting app

- Install prerequisites from docs/guides/BUILDING\.md
- Run bootstrap or activate to install all the required tools etc.
- `. scripts/bootstrap.sh` \- run this first\, or if builds fail
- `. scripts/activate.sh` \- faster\, use if you’ve already bootstrapped
and are just starting a new terminal

The build system we use is Ninja / GN. You can use a standard gn gen / ninja to
build as normal, or use the scripts to build specific variants. More information
about the build system can be found at [BUILDING.md](../guides/BUILDING.md). The
official quickstart guide for the build system is located ag
https://gn.googlesource.com/gn/+/master/docs/quick_start.md and a full reference
can be found at https://gn.googlesource.com/gn/+/main/docs/reference.md.

To build with the scripts, use scripts/build/build_examples\.py -
`scripts/build/build_examples.py targets` -
`scripts/build/build_examples.py --target <your target> build` - builds to
`out/<target_name>/`

Scripts can be used to build both the lighting app and chip tool

- Lighting app \(device\)
- `./scripts/build/build_examples.py --target linux-x64-light-no-ble build`
- This will build an executable to
`./out/linux-x64-light-no-ble/chip-lighting-app`

* NOTE that the host name (linux-x64 here) may be different on different
systems ex. darwin

- chip-tool (controller)
- `./scripts/build/build_examples.py --target linux-x64-chip-tool build`
- This will build an executable to `./out/linux-x64-chip-tool/chip-tool`

### Building / Interacting with Matter Examples

The first thing you need to do is to commission the device. First start up the
app in one terminal. By default it will start up with the default discriminator
(3840) and passcode (20202021) and save its non-volatile information in a KVS in
/temp/chip_kvs. You can change these, and multiple other options on the command
line. For a full description, use the `--help` command.

Start the lighting app in one terminal using

`./out/linux-x64-light-no-ble/chip-lighting-app`

The lighting app will print out all its setup information. You can get the setup
codes, discriminator and passcode from the logs.

Open a new terminal to use chip tool. Commission the device using:

`./out/linux-x64-chip-tool/chip-tool pairing code 0x12344321 MT:-24J0AFN00KA0648G0`

NOTE: pairing is the old name for commissioning. 0x12344321 is the node ID you
want to assign to the node. 0x12344321 is the default for testing.
MT:-24J0AFN00KA0648G0 is the QR code for a device with the default discriminator
and passcode. If you have changed these, the code will be different.

#### Basic device interactions - Sending a command

`./chip-tool onoff on 0x12344321 1`

where:

- onoff is the cluster name
- on is the command name
- 0x12344321 is the node ID you used for commissioning
- 1 is the endpoint

#### Basic device interactions - Reading an attribute

`./chip-tool onoff read on-off 0x12344321 1`

where:

- onoff is the cluster name
- read is the desired action
- on is the attribute name
- 0x12344321 is the node ID you used for commissioning
- 1 is the endpoint

0 comments on commit 3009427

Please sign in to comment.