Matter: Build a Matter IoT app with SmartThings Home API
matter build a matter iot app with smartthings home api objective learn how to create an iot app to onboard, control, remove, and share matter devices using smartthings home apis notesmartthings home apis are distributed only to authorized users if you want permission to use the apis, contact st matter@samsung com overview 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 app and smartthings home apis to help you quickly develop matter devices and use the smartthings ecosystem without needing to build your own iot ecosystem you can use smartthings home apis to onboard, control, remove, and share all matter devices when building your application other iot ecosystems can use the matter devices onboarded on your iot app through the multi-admin function for detailed information, go to partners smartthings com/matter set up your environment you will need the following 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 devices connected on the same network mobile device with matter virtual device app installed mobile device with developer mode and usb debugging enabled matter-enabled smartthings station onboarded with samsung account used for smartthings app tipyou can create a virtual device as a third-party iot device sample code noteyou can request permission to access the sample project file for this code lab by sending an email to st matter@samsung com start your project after downloading the sample code containing the project files, open your android studio and click open to open an existing project locate the downloaded android project from the directory and click ok commission the device you can onboard a matter-compatible device to the iot app by calling the commissiondevice api, which can lay the groundwork to control, remove, and share the device go to app > java > com samsung android matter home sample > feature > main in the mainviewmodel kt file, call the commissiondevice api to launch the onboarding activity and join the device to the smarththings fabric // ================================================================================= // codelab // step 1 create an instance of matter commissioning client // step 2 call the commissiondevice api to launch the onboarding activity in home service // step 3 set _intentsender value from return value of commissiondevice api // todo 1 device commission and join a device to smartthings fabric // todo 1 uncomment the following code blocks // --------------------------------------------------------------------------------- //val commissioningclient = matter getcommissioningclient //val intentsender = commissioningclient commissiondevice context //_intentsender value = intentsender // ================================================================================= control the device capabilities are core to the smartthings architecture they abstract specific devices into their underlying functions, which allows the retrieval of the state of a device component or control of the device function each device has its own appropriate capabilities therefore, each device has a different control api, and the more functions it supports, the more apis it has to use in this step, select a device type that you want to onboard and control using necessary home apis the level of modification complexity is assigned per each device contact sensorlevel 1 3 mins file path app > java > com samsung android matter home sample > feature > device file name contactsensorviewmodel kt // ================================================================================= // codelab level 1 // step 1 get contactsensor capability from device instance // step 2 get stream openclose value from contactsensor capability // step 3 set _openclose value for ui updating // todo 1 uncomment the following code blocks // --------------------------------------------------------------------------------- //device readcapability contactsensor ? openclose? collect { openclose -> // _openclose value = openclose //} // ================================================================================= // ================================================================================= // codelab level 1 // step 1 get battery capability from device instance // step 2 get stream battery value from battery capability // step 3 set _batterystatus value for ui updating // todo 2 uncomment the following code blocks // --------------------------------------------------------------------------------- //device readcapability battery ? battery? collect { battery -> // _batterystatus value = battery //} // ================================================================================= motion sensorlevel 1 3 mins file path app > java > com samsung android matter home sample > feature > device file name motionsensorviewmodel kt // ================================================================================= // codelab level 1 // step 1 get motionsensor capability from device instance // step 2 get stream occupied value from motionsensor capability // step 3 set _motionoccupied value for ui updating // todo 1 uncomment the following code blocks // --------------------------------------------------------------------------------- //device readcapability motionsensor ? occupied? collect { motionoccupied -> // _motionoccupied value = motionoccupied // timber d "occupied= $motionoccupied" //} // ================================================================================= // ================================================================================= // codelab level 1 // step 1 get battery capability from device instance // step 2 get stream battery value from battery capability // step 3 set _batterystatus value for ui updating // todo 2 uncomment the following code blocks // --------------------------------------------------------------------------------- //device readcapability battery ? battery? collect { battery -> // _batterystatus value = battery // timber d "battery= $battery" //} // ================================================================================= on-off switchlevel 2 4 mins file path app > java > com samsung android matter home sample > feature > device file name switchviewmodel kt // ================================================================================= // codelab level 2 // step 1 get switch capability from device instance // step 2 get stream onoff value from switch capability // step 3 set _onoff value for ui updating // todo 1 uncomment the following code blocks // --------------------------------------------------------------------------------- //device readcapability switch ? onoff? collect { onoff -> // _onoff value = onoff //} // ================================================================================= // ================================================================================= // codelab level 2 // step 1 get switch capability from device instance // step 2 control the device using the apis that supported by switch capability // toggle switch state based on onoff value // onoff == true call switch off // onoff == false call switch on // todo 2 uncomment the following code blocks // --------------------------------------------------------------------------------- //device readcapability switch ? let { switch -> // if onoff == true { // switch off // } else { // switch on // } //} // ================================================================================= smart locklevel 3 8 mins file path app > java > com samsung android matter home sample > feature > device file name smartlockviewmodel kt // ================================================================================= // codelab level 3 // step 1 get lock capability from device instance // step 2 get stream lockunlock value from lock capability // step 3 set _lockstatus value for ui updating // --------------------------------------------------------------------------------- // todo 1 copy code below device readcapability lock ? lockunlock? collect { lockunlock -> _lockstatus value = lockunlock } // ================================================================================= // ================================================================================= // codelab level 3 // step 1 get tamperalert capability from device instance // step 2 get stream tamperalert value from tamperalert capability // step 3 set _tamperstatus value for ui updating // --------------------------------------------------------------------------------- // todo 2 copy code below device readcapability tamperalert ? tamperalert? collect { tamperalert -> _tamperstatus value = tamperalert } // ================================================================================= // ================================================================================= // codelab level 3 // step 1 get battery capability from device instance // step 2 get stream battery value from battery capability // step 3 set _batterystatus value for ui updating // --------------------------------------------------------------------------------- // todo 3 copy code below device readcapability battery ? battery? collect { battery -> _batterystatus value = battery } // ================================================================================= // ================================================================================= // codelab level 3 // step 1 get lock capability from device instance // step 2 control the device using the apis that supported by lock capability // toggle lock state based on lockunlock value // lockunlock == true call lock // lockunlock == false call unlock // --------------------------------------------------------------------------------- // todo 4 copy code below device readcapability lock ? let { lock -> if lockunlock == true { lock lock } else { lock unlock } } // ================================================================================= blindslevel 3 8 mins file path app > java > com samsung android matter home sample > feature > device file name blindviewmodel kt // ================================================================================= // codelab level 3 // step 1 get windowshade capability from device instance // step 2 get stream windowshademode value from windowshade capability // step 3 set _windowshademode value for ui updating // --------------------------------------------------------------------------------- // todo 1 copy code below device readcapability windowshade ? windowshademode? collect { windowshademode -> timber d "windowshademode $windowshademode" _windowshademode value = windowshademode } // ================================================================================= // ================================================================================= // codelab level 3 // step 1 get windowshadelevel capability from device instance // step 2 get stream shadelevel value from windowshadelevel capability // step 3 set _shadelevel value for ui updating // --------------------------------------------------------------------------------- // todo 2 copy code below device readcapability windowshadelevel ? shadelevel? collect { shadelevel -> timber d "shadelevel $shadelevel" _shadelevel value = shadelevel } // ================================================================================= // ================================================================================= // codelab level 3 // step 1 get battery capability from device instance // step 2 get stream battery value from battery capability // step 3 set _batterystatus value for ui updating // --------------------------------------------------------------------------------- // todo 3 copy code below device readcapability battery ? battery? collect { battery -> _batterystatus value = battery } // ================================================================================= // ================================================================================= // codelab level 3 // step 1 get windowshade capability from device instance // step 2 control the device using the apis that supported by windowshade capability // send windowshade open/close/pause command based on controlcommand value // "open" call windowshade open // "close" call windowshade close // "pause" call windowshade pause // --------------------------------------------------------------------------------- // todo 4 copy code below device readcapability windowshade ? let { windowshade -> when controlcommand { "open" -> windowshade open "close" -> windowshade close "pause" -> windowshade pause } } // ================================================================================= extended color lightlevel 4 10 mins file path app > java > com samsung android matter home sample > feature > device file name lightviewmodel kt // ================================================================================= // codelab level 4 // step 1 get switch capability from device instance // step 2 get stream onoff value from switch capability // step 3 set _onoff value for ui updating // --------------------------------------------------------------------------------- // todo 1 copy code below device readcapability switch ? onoff? collect { onoff -> _onoff value = onoff } // ================================================================================= // ================================================================================= // codelab level 4 // step 1 get switchlevel capability from device instance // step 2 get stream level value from switchlevel capability // step 3 set _level value for ui updating // --------------------------------------------------------------------------------- // todo 2 copy code below device readcapability switchlevel ? level? collect { level -> _level value = level } // ================================================================================= // ================================================================================= // codelab level 4 // step 1 get switch capability from device instance // step 2 control the device using the apis that supported by switch capability // toggle switch state based on onoff value // onoff == true call switch off // onoff == false call switch on // --------------------------------------------------------------------------------- // todo 3 copy code below device readcapability switch ? let { switch -> if onoff == true { switch off } else { switch on } } // ================================================================================= // ================================================================================= // codelab level 4 // step 1 get switchlevel capability from device instance // step 2 control the device using the apis that supported by switchlevel capability // call switchlevel setlevel with percentage value // --------------------------------------------------------------------------------- // todo 4 copy code below timber d "target position = $percentage" device readcapability switchlevel ? setlevel percentage // ================================================================================= // ================================================================================= // codelab level 4 // step 1 get colorcontrol capability from device instance // step 2 control the device using the apis that supported by colorcontrol capability // call colorcontrol setcolor with hue,saturation value // --------------------------------------------------------------------------------- // todo 5 copy code below timber d "hue $hue,saturation $saturation" device readcapability colorcontrol ? setcolor hue todouble , saturation todouble // ================================================================================= // ================================================================================= // codelab level 4 // step 1 get colortemperature capability from device instance // step 2 control the device using the apis that supported by colortemperature capability // call colortemperature setcolortemperature with temperature // --------------------------------------------------------------------------------- // todo 6 copy code below device readcapability colortemperature ? setcolortemperature temperature // ================================================================================= video playerlevel 4 10 mins file path app > java > com samsung android matter home sample > feature > device file name televisionviewmodel kt // ================================================================================= // codelab level 4 // step 1 get switch capability from device instance // step 2 get stream onoff value from switch capability // step 3 set _onoff value for ui updating // --------------------------------------------------------------------------------- // todo 1 copy code below device readcapability switch ? onoff? collect { onoff -> _onoff value = onoff } // ================================================================================= // ================================================================================= // codelab level 4 // step 1 get mediaplayback capability from device instance // step 2 get stream mediaplaybackstate value from mediaplayback capability // step 3 set _mediaplaybackstate value for ui updating // --------------------------------------------------------------------------------- // todo 2 copy code below device readcapability mediaplayback ? mediaplaybackstate? collect { mediaplaybackstate -> _mediaplaybackstate value = mediaplaybackstate } // ================================================================================= // ================================================================================= // codelab level 4 // step 1 get switch capability from device instance // step 2 control the device using the apis that supported by switch capability // toggle switch state based on onoff value // onoff == true call switch off // onoff == false call switch on // --------------------------------------------------------------------------------- // todo 3 copy code below device readcapability switch ? let { switch -> if onoff == true { switch off } else { switch on } } // ================================================================================= // ================================================================================= // codelab level 4 // step 1 get mediaplayback capability from device instance // step 2 control the device using the apis that supported by mediaplayback capability // send mediaplayback play/pause/stop/rewind/fastforward command based on controlcommand value // "play" call mediaplayback play and setplaybackstatus with playbackstatus playing // "pause" call mediaplayback pause and setplaybackstatus with playbackstatus paused // "stop" call mediaplayback stop and setplaybackstatus with playbackstatus stopped // "rewind" call mediaplayback rewind and setplaybackstatus with playbackstatus rewinding // "fastforward" call mediaplayback fastforward and setplaybackstatus with playbackstatus fastforwarding // --------------------------------------------------------------------------------- // todo 4 copy code below device readcapability mediaplayback ? let { mediaplayback -> when controlcommand { "play" -> { mediaplayback play mediaplayback setplaybackstatus playbackstatus playing } "pause" -> { mediaplayback pause mediaplayback setplaybackstatus playbackstatus paused } "stop" -> { mediaplayback stop mediaplayback setplaybackstatus playbackstatus stopped } "rewind" -> { mediaplayback rewind mediaplayback setplaybackstatus playbackstatus rewinding } "fastforward" -> { mediaplayback fastforward mediaplayback setplaybackstatus playbackstatus fastforwarding } } } // ================================================================================= // ================================================================================= // codelab level 4 // step 1 get mediatrackcontrol capability from device instance // step 2 control the device using the apis that supported by mediatrackcontrol capability // send mediatrack nexttrack/previoustrack command based on controlcommand value // "nexttrack" call mediatrack nexttrack // "previoustrack" call mediatrack previoustrack // --------------------------------------------------------------------------------- // todo 5 copy code below device readcapability mediatrackcontrol ? let { mediatrack -> when controlcommand { "nexttrack" -> mediatrack nexttrack "previoustrack" -> mediatrack previoustrack } } // ================================================================================= // ================================================================================= // codelab level 4 // step 1 get keypadinput capability from device instance // step 2 control the device using the apis that supported by keypadinput capability // call keypadinput sendkey with key value // --------------------------------------------------------------------------------- // todo 6 copy code below device readcapability keypadinput ? sendkey key // ================================================================================= thermostatlevel 5 13 mins file path app > java > com samsung android matter home sample > feature > device file name thermostatviewmodel kt // ================================================================================= // codelab level 5 // step 1 get thermostatmode capability from device instance // step 2 get stream thermostatmode value from thermostatmode capability // step 3 set _systemmode value for ui updating // --------------------------------------------------------------------------------- // todo 1 copy code below device readcapability thermostatmode ? thermostatmode? collect { thermostatmode -> timber d "viewmodel thermostatmode $thermostatmode" _systemmode value = thermostatmode } // ================================================================================= // ================================================================================= // codelab level 5 // step 1 get thermostatfanmode capability from device instance // step 2 get stream thermostatfanmode value from thermostatfanmode capability // step 3 set _fanmode value for ui updating // --------------------------------------------------------------------------------- // todo 2 copy code below device readcapability thermostatfanmode ? thermostatfanmode? collect { fanmode -> _fanmode value = fanmode } // ================================================================================= // ================================================================================= // codelab level 5 // step 1 get temperaturemeasurement capability from device instance // step 2 get stream temperature value from temperaturemeasurement capability // step 3 set _temperature value for ui updating // --------------------------------------------------------------------------------- // todo 3 copy code below device readcapability temperaturemeasurement ? temperature? collect { temperature -> _temperature value = temperature } // ================================================================================= // ================================================================================= // codelab level 5 // step 1 get thermostatcoolingsetpointbattery capability from device instance // step 2 get stream coolingsetpoint value from thermostatcoolingsetpoint capability // step 3 set _occupiedcoolingsetpoint value for ui updating // --------------------------------------------------------------------------------- // todo 4 copy code below device readcapability thermostatcoolingsetpoint ? coolingsetpoint? collect { coolingsetpoint -> _occupiedcoolingsetpoint value = coolingsetpoint } // ================================================================================= // ================================================================================= // codelab level 5 // step 1 get thermostatheatingsetpoint capability from device instance // step 2 get stream heatingsetpoint value from thermostatheatingsetpoint capability // step 3 set _occupiedheatingsetpoint value for ui updating // --------------------------------------------------------------------------------- // todo 5 copy code below device readcapability thermostatheatingsetpoint ? heatingsetpoint? collect { heatingsetpoint -> _occupiedheatingsetpoint value = heatingsetpoint } // ================================================================================= // ================================================================================= // codelab level 5 // step 1 get relativehumiditymeasurement capability from device instance // step 2 get stream humidity value from relativehumiditymeasurement capability // step 3 set _humidity value for ui updating // --------------------------------------------------------------------------------- // todo 6 copy code below device readcapability relativehumiditymeasurement ? humidity? collect { humidity -> _humidity value = humidity } // ================================================================================= // ================================================================================= // codelab level 5 // step 1 get battery capability from device instance // step 2 get stream battery value from battery capability // step 3 set _batterystatus value for ui updating // --------------------------------------------------------------------------------- // todo 7 copy code below device readcapability battery ? battery? collect { battery -> _batterystatus value = battery } // ================================================================================= // ================================================================================= // codelab level 5 // step 1 get thermostatmode capability from device instance // step 2 control the device using the apis that supported by thermostatmode capability // change thermostatmode state based on systemmode value // thermostatsystemmode off call thermostatmode off // thermostatsystemmode cool call thermostatmode cool // thermostatsystemmode heat call thermostatmode heat // thermostatsystemmode auto call thermostatmode auto // --------------------------------------------------------------------------------- // todo 8 copy code below device readcapability thermostatmode ? let { thermostatmode -> when systemmode { thermostatsystemmode off -> thermostatmode off thermostatsystemmode cool -> thermostatmode cool thermostatsystemmode heat -> thermostatmode heat thermostatsystemmode auto -> thermostatmode auto } } // ================================================================================= // ================================================================================= // step 1 get thermostatfanmode capability from device instance // step 2 control the device using the apis that supported by thermostatfanmode capability // change thermostatfanmode state based on fanmode value // thermostatfanmodeenum auto call thermostatfanmode fanauto // thermostatfanmodeenum circulate call thermostatfanmode fancirculate // thermostatfanmodeenum followschedule call thermostatfanmode setthermostatfanmode with followschedule // thermostatfanmodeenum on call thermostatfanmode fanon // --------------------------------------------------------------------------------- // todo 9 copy code below device readcapability thermostatfanmode ? let { thermostatfanmode -> when fanmode { thermostatfanmodeenum auto -> thermostatfanmode fanauto thermostatfanmodeenum circulate -> thermostatfanmode fancirculate thermostatfanmodeenum followschedule -> thermostatfanmode setthermostatfanmode "followschedule" thermostatfanmodeenum on -> thermostatfanmode fanon } } // ================================================================================= // ================================================================================= // codelab level 5 // step 1 get thermostatheatingsetpoint capability value from device instance // step 2 increase _occupiedheatingsetpoint value that have current heating value // step 3 if new increased value is under value_max 104 , // call setheatingsetpoint of thermostatheatingsetpoint capability with new increased value // --------------------------------------------------------------------------------- // todo 10 copy code below device readcapability thermostatheatingsetpoint ? let { heatingsetpoint -> val nextvalue = _occupiedheatingsetpoint value!! + 1 if nextvalue < value_max { heatingsetpoint setheatingsetpoint nextvalue } } // ================================================================================= // ================================================================================= // codelab level 5 // step 1 get thermostatheatingsetpoint capability value from device instance // step 2 decrease _occupiedheatingsetpoint value that have current heating value // step 3 if new decreased value is over value_min 32 , // call setheatingsetpoint of thermostatheatingsetpoint capability with new decreased value // --------------------------------------------------------------------------------- // todo 11 copy code below device readcapability thermostatheatingsetpoint ? let { heatingsetpoint -> val nextvalue = _occupiedheatingsetpoint value!! - 1 if nextvalue > value_min { heatingsetpoint setheatingsetpoint nextvalue } } // ================================================================================= // ================================================================================= // codelab level 5 // step 1 get thermostatcoolingsetpoint capability value from device instance // step 2 increase _occupiedcoolingsetpoint value that have current cooling value // step 3 if new increased value is under value_max 104 , // call setcoolingsetpoint of thermostatcoolingsetpoint capability with new increased value // --------------------------------------------------------------------------------- // todo 12 copy code below device readcapability thermostatcoolingsetpoint ? let { coolingsetpoint -> val nextvalue = _occupiedcoolingsetpoint value!! + 1 if nextvalue < value_max { coolingsetpoint setcoolingsetpoint nextvalue } } // ================================================================================= // ================================================================================= // codelab level 5 // step 1 get thermostatcoolingsetpoint capability value from device instance // step 2 decrease _occupiedcoolingsetpoint value that have current cooling value // step 3 if new decreased value is over value_min 32 , // call setcoolingsetpoint of thermostatcoolingsetpoint capability with new decreased value // --------------------------------------------------------------------------------- // todo 13 copy code below device readcapability thermostatcoolingsetpoint ? let { coolingsetpoint -> val nextvalue = _occupiedcoolingsetpoint value!! - 1 if nextvalue > value_min { coolingsetpoint setcoolingsetpoint nextvalue } } // ================================================================================= noteyou can find related files in android studio by going to edit menu> find > find in files and entering the keyword "codelab" remove the device using removedevice api, you can remove the device from your iot app and the smartthings fabric go to app > java > com samsung android matter home sample > feature > device > base in the baseviewmodel kt file, call the removedevice api to launch the removedevice activity // ================================================================================= // [codelab] device remove from smartthings fabric // step 1 create an instance of matter commissioning client // step 2 call the removedevice api to launch the removedevice activity in home service // step 3 set _intentsender value from return value of removedevice api // todo 1 uncomment the following code blocks // --------------------------------------------------------------------------------- //val commissioningclient = matter getcommissioningclient //val intentsender = commissioningclient removedevice // context, // commissioningclient removedevicerequest deviceid // //_intentsenderforremovedevice value = intentsender // ================================================================================= share the device matter devices can be shared with other matter-compatible iot platforms, such as google home, using home apis without resetting the device while connected to smartthings to perform this operation, it is necessary to enter the commissioning mode without resetting the device in the baseviewmodel kt file, call the sharedevice api to launch the sharedevice activity // ================================================================================= // [codelab] device share to other platforms // step 1 create an instance of matter commissioning client // step 2 call the sharedevice api to launch the sharedevice activity in home service // step 3 set _intentsender value from return value of sharedevice api // todo 1 uncomment the following code blocks // --------------------------------------------------------------------------------- //val commissioningclient = matter getcommissioningclient //val intentsender = commissioningclient sharedevice // context, // commissioningclient sharedevicerequest deviceid // //_intentsenderforsharedevice value = intentsender // ================================================================================= build and run the iot app run the sample app to build and run your iot app, follow these steps using a usb cable, connect your mobile device select the sample iot app from the run configurations menu in the android studio then, select the connected device in the target device menu click run onboard to onboard the virtual device go to the matter virtual device app then, select and set up the virtual device type you want to control click save click start to show the qr code for onboarding go to the sample iot app and click the + button then, onboard the virtual device by scanning its qr code control by sample iot app in the sample iot app, control the virtual device by using its various functions such as on and off for switch you're done! congratulations! you have successfully achieved the goal of this code lab topic now, you can create a matter-compatible iot application with smartthings home apis by yourself! learn more by going to smartthings matter libraries