project-chip/connectedhomeip

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.

Matter

Builds

Tests

Tools

Documentation

• Matter SDK documentation page

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:

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:

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.

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.

connectedhomeip's Issues

Build warning

Warning while compiling main build: https://github.com/project-chip/connectedhomeip/runs/499611869?check_suite_focus=true

../../third_party/lwip/repo/lwip/src/core/udp.c: In function ‘udp_sendto_if_src’:
63
../../third_party/lwip/repo/lwip/src/core/udp.c:869:26: warning: passing argument 2 of ‘netif_apply_pcb’ from incompatible pointer type [-Wincompatible-pointer-types]
64
   netif_apply_pcb(netif, pcb);
65
                          ^~~
66
In file included from ../../third_party/lwip/repo/lwip/src/include/lwip/udp.h:46:0,
67
                 from ../../third_party/lwip/repo/lwip/src/core/udp.c:52:
68
../../third_party/lwip/repo/lwip/src/include/lwip/netif.h:371:6: note: expected ‘struct ip_pcb *’ but argument is of type ‘struct udp_pcb *’
69
 void netif_apply_pcb(struct netif *netif, struct ip_pcb *pcb);
70
      ^~~~~~~~~~~~~~~
71

Thread is disabled in Device Configs for EFR32

Problem

The following config items were removed from EFR32 CHIPDevicePlatformConfig.h files.

EFR32:

connectedhomeip/src/include/platform/EFR32/CHIPDevicePlatformConfig.h

Line 35 in ca9dfc2

#define CHIP_DEVICE_CONFIG_ENABLE_THREAD 0

connectedhomeip/src/include/platform/EFR32/CHIPDevicePlatformConfig.h

Line 125 in ca9dfc2

#define CHIP_DEVICE_CONFIG_ENABLE_THREAD_TELEMETRY 0

Proposed Solution

Figure out how to bring Thread Support back in.

Update .gitignore and BuildConfig header

With the new automake based build system, each build leaves many untracked files in the tree.
It also overwrites the BuildConfig.h that's included in the tree. This file can most likely be removed.

No APIs to support symmetric key based payload encryption available in CHIP

Problem

No APIs exist in CHIP to support symmetric key based payload encryption

Proposed Solution

We are going to use existing code in the open source HAP ADK to implement encrypting the payload that gets sent over the wire. This issue tracks porting over the existing symmetric key based encryption from HAP ADK. This does NOT deal with the topic of how those keys are obtained / exchanged in the first place.

Specifically we should pull the code in these files from https://github.com/apple/HomeKitADK

1. PAL/Crypto/MbedTLS/HAPMbedTLS.c
2. PAL/Crypto/OpenSSL/HAPOpenSSL.c
3. PAL/HAPBase+Crypto.c
4. HAP/HAPSession.c : Some of the methods like HAPSessionEncryptControlMessage and HAPSessionEncryptControlMessageWithAAD if not everything

TimeSync Service is not supported on EFR32

Problem

#125 removed the TimeSync Service configuration from the EFR32 Platform Config.
Reference:

connectedhomeip/src/include/platform/EFR32/CHIPDevicePlatformConfig.h

Line 38 in ca9dfc2

#define CHIP_DEVICE_CONFIG_ENABLE_CHIP_TIME_SERVICE_TIME_SYNC 0

Proposed Solution

Figure out what needs to be done to bring this support back in

Establish operational credentials with accessory

Establish operational credentials with accessory

Sub of TLF: [SC&T] Device Onboarding #127

Build instructions should have make instead of Makefile-Standalone

I tried the build instructions:

$ brew install make autoconf automake libtool
$ brew install llvm@9
$ git clean -fdx
$ ./bootstrap-configure
$ make -f Makefile-Standalone
# got an error at this point telling me to run make distclean
$ make distclean
$ make -f Makefile-Standalone
# Next I tried to run some tests (previous from Building.md)
$ cd src/setup_payload
$ make check
# got error: make: *** No rule to make target `check'. Stop.
# where 1-7 where run at top level directory

I then ran:

$ git clean -xdf
$ ./bootstrap-configure
$ make

And then make check worked

Enable codecov

Once Marketplace access is available, we should enable:
https://github.com/marketplace/codecov

Setup a secure channel using PAKE

This is an umbrella issue tracking work to setup a secure channel using a PAKE

Sub of TLF: [SC&T] Device Onboarding #127

Manual onboarding payload generator

Problem

Add support to generate the manual entry code.

Enable LGTM

We should enable LGTM as soon as possible for all PRs:
https://github.com/marketplace/lgtm

Reenable TIME_SERVICE_TIME_SYNC

Problem

#104 disabled TIME_SERVICE_TIME_SYNC at

connectedhomeip/src/include/platform/CHIPDeviceConfig.h

Line 407 in ca9dfc2

#ifndef CHIP_DEVICE_CONFIG_ENABLE_CHIP_TIME_SERVICE_TIME_SYNC

and

connectedhomeip/src/include/platform/nRF5/CHIPDevicePlatformConfig.h

Line 43 in ca9dfc2

#define CHIP_DEVICE_CONFIG_ENABLE_CHIP_TIME_SERVICE_TIME_SYNC 0

#125 removed the TimeSync Service configuration from the EFR32 Platform Config.
Reference:

connectedhomeip/src/include/platform/EFR32/CHIPDevicePlatformConfig.h

Line 38 in ca9dfc2

#define CHIP_DEVICE_CONFIG_ENABLE_CHIP_TIME_SERVICE_TIME_SYNC 0

Proposed Solution

Check if these need to be enabled. If required, enable and fix the associated issues.

Support clang-format in PR

You might find OpenThread's scripts around clang-format useful:

• https://github.com/openthread/openthread/blob/master/script/make-pretty
• https://github.com/openthread/openthread/blob/master/script/clang-format.sh
• https://github.com/openthread/openthread/blob/master/script/clang-format-check.sh

Originally posted by @jwhui in #2 (comment)

_GetQRCodeString() is not implemented

Problem

#104 removed support for DeviceDescriptor from ConfigurationManager. That in turn removed the implementation for _GetQRCodeString().

Proposed Solution

Identify the correct/new API that replaces DeviceDescriptor. Re-implement _GetQRCodeString using this API.

QR code base45 string parser

Problem

Implement code to convert a base45 string to a SetupPayload object.

Provision network credentials to accessory

This is an umbrella issue tracking work needed to provision network credentials to accessory

Sub of TLF: [SC&T] Device Onboarding #127

Pretty check is failing build

Problem

Pretty check is failing build presently

Proposed Solution

Please fix :)

Handler in GenericSoftwareUpdateManager may need to be resurrected

Problem

#104 removed the following functions from GenericSoftwareUpdateManagerImpl.
SoftwareUpdateFailed
HandleStatusReport
HandleServiceBindingEvent
HandleResponse
OnKeyError
OnResponseTimeout

Proposed Solution

Evaluate if these functions are needed. If so, identify the replacement APIs for ExchangeContext, and Binding and reimplement these functions.

Fix EFR32 Build Support file dependencies

Problem

#125 removed the following library dependencies from efr32-chip.mk

- Removed: linking with warm
- Removed: linking with mincrypt
- Removed: linking with uECC

#125 also removed the following library dependencies and extra sources from efr32-app.mk

- Removed: linking with freertos
- Removed: References to linker scripts
- Removed: References to extra source files like $(EFR32_SDK_ROOT)/util/third_party/mbedtls/sl_crypto/src/trng.c

Proposed Solution

These are very likely required for any CHIP based app to actually work on the EFR32 platform. Figure out how to bring them back.

Enable restyled.io

Config is in, we should have this enabled for PRs:
https://github.com/marketplace/restyled-io

Awaiting GitHub marketplace access

Fix failing distcheck

Problem

Distcheck fails on CI and locally.

Proposed Solution

Figure out what this does and fix it.

Ready README.md for open source

Problem

Per @robszewczyk we need to update the main README.md file with final wording before going open source

Run clang-tidy locally

How do / can I run clang-tidy locally on my MacBook Pro? Is that mechanism different than what we use for CI?

Originally posted by @gerickson in #1

We should have a way to run clang-tidy locally

Device Onboarding

[SC&T] OOB Pairing and Onboarding

This is a high level umbrella issue tracking work needed to support device onboarding.
Some of the sub-tasks are

• Initial device discovery (rendezvous) #128
• Setup a secure channel using PAKE #130
• Provision network credentials to accessory #131
• Establish operational credentials with accessory #132

Enable Coverity

We also use Coverity, which supports public, open source projects free of charge. Between LGTM, clang static analysis, and Coverity, there is a non-overlapping Venn diagram of issues caught.

Originally posted by @gerickson in #37 (comment)

Mock platforms

Problem

Platform library testing for EFR32 and nRF5 currently require the platforms' DKs to be installed.

Proposed Solution

• build mocks for each of the supported platforms
• add unit tests for the functionality that consume the mocks

bootstrap-configure doesn't work in ubuntu

Problem

developer@17af346013fa:~/connectedhomeip$ ./bootstrap-configure
./bootstrap-configure: 42: ./bootstrap-configure: pushd: not found

Proposed Solution

bootstrap incorrectly uses #!/bin/sh at the top, but it's using a bash capability. Needs to be changed to !#/bin/bash

Initial device discovery (rendezvous)

This issue tracks Initial device discovery aka rendezvous.

Sub of TLF: [SC&T] Device Onboarding #127

Master seems broken for me.

Summary: Master seems broken for me.

Steps to reproduce:

1. clone repo
2. cd into repo
3. git clean -fdx
4. ./bootstrap-configure
5. make -f Makefile-Standalone

This is the error I am seeing -
checking whether make supports nested variables... yes
configure: error: source directory already configured; run "make distclean" there first
make: *** [build/x86_64-apple-darwin/config.status] Error 1

Docker images live in developer-owned repositories

Problem

//integrations/docker/images/* directories build and push to developer orgs, should point to something owned by project-chip.

Proposed Solution

create a docker.io org
update build.sh(s)
update any resulting docker-based builds to pull from official repositories

HashLengthAndBase64Value() needs to be reimplemented

Problem

#104 deleted implementation of HashLengthAndBase64Value() and corresponding calls to it. This was done because Platform::Security module is not available.

Proposed Solution

Reimplement the function with available APIs. Add the calls to function from where it was removed.

Deleted code reference:
https://github.com/project-chip/connectedhomeip/blob/master/src/include/platform/internal/GenericConfigurationManagerImpl.ipp#L1053

CLA enforcement

Problem

Per @robszewczyk - Need a way to enforce CLA is signed before a pull request can be approved by a developer

Proposed Solution

@robszewczyk fixes it :)

Ready CONTRIBUTING.md

Problem

Per @robszewczyk we need to go over the CONTRIBUTING.md before opening up the repository.

UserSelectedMode APIs are returning dummy values

Problem

#104 removed support for DeviceDescriptor. Due to this UserSelectedMode APIs in GenericConnectivityManagerImpl.h are returning dummy values.

Proposed Solution

Identify the replacement APIs for DeviceDescriptor, and reimplemented the following functions.
_IsUserSelectedModeActive
_SetUserSelectedMode
_GetUserSelectedModeTimeout
_SetUserSelectedModeTimeout

EFR32 platform layer code is not being built

Problem

The platform code for EFR32 is imported. But it's not currently being built.

Proposed Solution

Import and fix makefiles for this platform.

Fix OpenThread Dependencies for EFR32

Problem

#125 Removed OpenThread dependencies from efr32-chip.mk and in the platform code.
It also removed dependencies on missing SEGGER header files(ref: src/platform/EFR32/Logging.cpp) and so if a project adds EFR32_LOG_ENABLED to their CHIPProjectConfig.h the build will not work.

The missing SEGGER headers, for example, are part of OpenThread.

Proposed Solution

Figure out if OpenTread is a hard dependency for all EFR32 apps (followed the openweave demo example) and if not bring in the missing SEGGER dependencies and make sure EFR32_LOG_ENABLED can be set.

Build failing

Problem

Build is failing here:

https://github.com/project-chip/connectedhomeip/runs/528993246?check_suite_focus=true

Assigning @gerickson & @rwalker-apple to talk about process, and the fix here :)

nRF5 platform makefile is not building all source code

Problem

The following files are not being built, as they are heavily dependent on removed code (as part of #104 )

ConfigurationManagerImpl.cpp
ThreadStackManagerImpl.cpp
GroupKeyStoreImpl.cpp
SoftwareUpdateManagerImpl.cpp
Entropy.cpp

Removed from src/platform/Makefile.am

Proposed Solution

Fix the code, and add to makefile.

Create new CHIP specific UUIDs for CHIPoBLE

Problem

CHIP currently uses WoBLE UUIDs. This needs to be updated.

connectedhomeip/src/include/platform/EFR32/gatt.xml

Lines 83 to 84 in 2e6b8fd

	<!--CHIPoBLEChar_Rx-->
	<characteristic id="CHIPoBLEChar_Rx" name="CHIPoBLEChar_Rx" sourceId="custom.type" uuid="18EE2EF5-263D-4559-959F-4F9C429F9D11">

Proposed Solution

Generate UUIDs for CHIP

Enable travis-ci

Let's move to travis for build steps. Waiting on ability to enable it from the market place.

Certificate compression mechanism

This is an umbrella radar tracking work needed for certificate compression

Bring in extra source files for Build Support mk files

Problem

mbedtls was removed from the efr32-app.mk

Proposed Solution

Figure out whether mbedtls is a hard dependency for all efr32 apps and test the demo app flow with this brought in.

Max serial number length and firmware revision length are hardcoded

Problem

#104 hardcoded the lengths to 32 bytes. This was done as ChipDeviceDescriptor is not implemented yet.

https://github.com/project-chip/connectedhomeip/blob/master/src/include/platform/ConfigurationManager.h#L62

Proposed Solution

Once a device descriptor is implemented, read these two values from its configuration.

Improve BUILDING.md instructions on how to use autotools.

Problem

Could someone with experience update the BUILDING.md doc with workflow best practices?

• how to build the entire source,
• how to build a specific set of sub-folders / modules, add new source files,
• run & debug unit tests,
• run and analyze code coverage results,
• run formatting checks, etc.

BLE Device name is hardcoded

Problem

BLEManagerImpl.cpp computes device name using FabricState.LocalNodeId(). This was removed (and hardcoded to 0) in #104 for nRF5 and in #125 for EFR32.

Proposed Solution

Identify the correct replacement for LocalNodeId and use that to compute device name.

Code reference:
nRF5 -

connectedhomeip/src/platform/nRF5/BLEManagerImpl.cpp

Lines 251 to 253 in ca9dfc2

	snprintf(devNameBuf, sizeof(devNameBuf), "%s%04" PRIX32,
	CHIP_DEVICE_CONFIG_BLE_DEVICE_NAME_PREFIX,
	(uint32_t)0);

EFR32 -

connectedhomeip/src/platform/EFR32/BLEManagerImpl.cpp

Lines 584 to 585 in ca9dfc2

	snprintf(mDeviceName, sizeof(mDeviceName), "%s%04" PRIX32, CHIP_DEVICE_CONFIG_BLE_DEVICE_NAME_PREFIX,
	(uint32_t)0);

Linux/Posix implementation of Device Layer

Problem

A new implementation of device layer for Linux/Posix platform is needed.

Proposed Solution

Implement the new device layer.

Tracking list for the solution [@turon]:

• Addd initial PlatformMgr: select loop, entropy, time [PR #614]
• Add ConfigurationManager and FileStore support [#738]
• Add ConnectivityManager and WiFi support [#739]
• Extend ConnectivityManager with Thread support [#740]
• Add BleManager support for Linux (bluez) [#741]
• Add BleManager for Darwin
• Add support for process termination [#742]
• Extend tests
• Add example app

nlbuild-autotools is out of date

Problem

"Upstream" nlbuild-autotools has bug fixes, updates this project lacks

Proposed Solution

• apply git subtree magic
• document git subtree magic so that others may apply in future

nRF5 platform layer code is not being built

Problem

The platform code for nRF5 is imported. But it's not currently being built.

Proposed Solution

Import and fix makefiles for this platform.

Not all EFR32 platform source files are being built

Problem

#125 removed rules to build some source files in the EFR32 platform.

EFR32/NetworkProvisioningServerImpl.cpp
EFR32/ThreadStackManagerImpl.cpp	
EFR32/GroupKeyStoreImpl.cpp
EFR32/Entropy.cpp
EFR32/SoftwareUpdateManagerImpl.cpp
EFR32/ConfigurationManagerImpl.cpp

Removed from src/platform/Makefile.am

Proposed Solution

Determine which bits are needed and how to bring them in.

HandleSessionEstablished may need to be resurrected

Problem

#104 removed HandleSessionEstablished from GenericPlatformManagerImpl, as it was dependent on ChipSecurityManager. This code may need to be resurrected.

Proposed Solution

Evaluate if the code is needed. If so, redefine the function interface and implement it.

Code Reference: https://github.com/project-chip/connectedhomeip/blob/master/src/include/platform/internal/GenericPlatformManagerImpl.ipp#L307