Developing a Matter IoT Application with the SmartThings Home API
HyoJung Lee
Matter is an open-source connectivity standard for smart home and Internet of Things (IoT) devices. It is a secure, reliable, and seamless cross-platform protocol for connecting compatible devices and systems with one another.
SmartThings provides the Matter virtual device application and SmartThings Home APIs to help you quickly develop Matter devices and use the SmartThings ecosystem without needing to build your own IoT ecosystem.
Supporting IoT devices that can be operated from outside the home requires significant infrastructure investment. A cloud server must be built and maintained to deliver commands to the home, and if the device uses a mesh network technology such as Thread, the user needs to have a supported hub in the home. Users are also typically uninterested in purchasing multiple hubs to support all the brands of IoT devices that they own.
The SmartThings Home API, announced at SDC 2023, allows you to leverage the SmartThings infrastructure for your own Matter and IoT products. The API enables you to use the SmartThings Cloud, which means your application can support Matter devices connected to any of the 1.7 million SmartThings hubs worldwide.
In this tutorial, you will learn how to use the SmartThings Home APIs to develop an IoT application that onboards, controls, shares, and removes a smart lock device.
For more information about SmartThings Matter, see Matter in SmartThings.
Prerequisites
To follow along with this tutorial, you need the following hardware and software:
- Host PC running on Windows 10 (or higher) or Ubuntu 20.04 (x64)
- Android Studio (latest version recommended)
- Java SE Development Kit (JDK) 11 or later
- Mobile devices & SmartThings Station connected on the same network:
- Mobile device with Matter virtual device application installed
- Mobile device with Developer Mode and USB Debugging enabled
- Matter-enabled SmartThings Station onboarded with the Samsung account used for SmartThings
Commission the device
To onboard a Matter-compatible device to your IoT application, you must commission the device, joining it to the SmartThings fabric.
Download the sample application project and open it in Android Studio. The following steps are implemented in the MainViewModel.kt file at the path app > java > com.samsung.android.matter.home.sample > feature > main.
Step 1. Create an instance of the Matter commissioning client.
Step 2. Call the commissionDevice() function to launch the Onboarding activity in Home Service.
Step 3. Set the value of _intentSender.value to the returned value.
// Todo 1
val commissioningClient = Matter.getCommissioningClient()
val intentSender = commissioningClient.commissionDevice(context)
_intentSender.value = intentSender
Control the device
Capabilities are the core of the SmartThings architecture. They abstract devices into their underlying functionalities, which allows you to retrieve the state of a specific device component or control specific functionality.
Each device has its own set of appropriate capabilities, each controlled with its own API function. Consequently, the more capabilities the device supports, the more application code is needed to implement it.
The following steps demonstrate implementing the capabilities for a smart lock device. They are implemented in the SmartLockViewModel.kt file at the path app > java > com.samsung.android.matter.home.sample > feature > device.
Step 1. To retrieve lock, tamper and battery status of a device capability:
a. Retrieve the appropriate capability from the device instance.
b. Extract the stream value for the appropriate feature from the capability.
c. Store the retrieved value for updating the UI.
// Todo 2
device.readCapability(Lock)?.lock?.collect { lockUnlock ->
_lockStatus.value = lockUnlock
}
// Todo 3
device.readCapability(TamperAlert)?.tamper?.collect { tamperAlert ->
_tamperStatus.value = tamperAlert
}
// Todo 4
device.readCapability(Battery)?.battery?.collect { battery ->
_batteryStatus.value = battery
}
Step 2. To control the lock status:
a. Retrieve the Lock capability from the device instance.
b. If lockStatus is unlock, call lock() function to close it.
c. If lockStatus is not unlock, call unlock() function to open it.
// Todo 5
device.readCapability(Lock)?.let { lock ->
when (_lockStatus.value) {
LockStatus.Unlocked.statusName -> lock.lock()
else -> lock.unlock()
}
}
Share the device
Using the SmartThings Home API, you can share Matter devices connected to SmartThings with other Matter-compatible IoT platforms without resetting the device. This enables the user to control the same device through additional controller applications, such as Google Home.
The following steps are implemented in the BaseViewModel.kt file at the path app > java > com.samsung.android.matter.home.sample > feature > device > base.
Step 1. Create an instance of the Matter commissioning client.
Step 2. To launch the ShareDevice activity in Home Service, call the shareDevice() function.
Step 3. Set the value of _intentSenderForShareDevice.value to the returned value.
// Todo 6
val commissioningClient = Matter.getCommissioningClient()
val intentSender = commissioningClient.shareDevice(
context,
CommissioningClient.ShareDeviceRequest(deviceId)
)
_intentSenderForShareDevice.value = intentSender
Remove the device
You can remove the device from the IoT application and the SmartThings fabric.
The following steps are implemented in the BaseViewModel.kt file at the path app > java > com.samsung.android.matter.home.sample > feature > device > base.
Step 1. Create an instance of the Matter commissioning client.
Step 2. To launch the RemoveDevice activity in Home Service, call the removeDevice() function.
Step 3. Set the value of _intentSenderForRemoveDevice.value to the returned value.
// Todo 7
val commissioningClient = Matter.getCommissioningClient()
val intentSender = commissioningClient.removeDevice(
context,
CommissioningClient.RemoveDeviceRequest(deviceId)
)
_intentSenderForRemoveDevice.value = intentSender
Test the application
To test the sample IoT application with a virtual smart lock device:
Step 1. Build and run the project on your Android device. When you launch the application, it is synced to the SmartThings application and your connected Matter devices and hubs are listed on the home screen.
Step 2. To create a virtual smart lock device:
a. Launch the Matter virtual device application on your other mobile device.
b. Select “Door lock,” then tap “Save” and “Start” to receive a QR code.
Step 3. Within the sample IoT application, to onboard the virtual smart lock, tap “+” and scan the QR code.
Step 4. To lock and unlock the virtual smart lock, tap the button in the IoT application.
Conclusion
This tutorial has demonstrated how you can create an application to onboard and control a smart lock using the SmartThings Home API. To learn about onboarding and controlling other device types, go to Code Lab (Matter: Build a Matter IoT app with SmartThings Home API).
For more information about SmartThings Matter, see Matter in SmartThings.
