How to use device preferences

This document describes how to add Device Preferences on direct-connected device and relavant information.

Prerequisite

Device Preferences

A Device Preference is a configuration that enables users to customize the behavior of their device. A Device Preference is typically set to provide users with a way to tweak their device, and may optionally include a default value. Users can change a Device Preference to customize their device by tapping their device in the SmartThings app, tapping the overflow (3-dot) menu icon, and tapping settings.
You can use Standard Device Preferences or create one for your own device.
Please visit SmartThings Developers website for more details.

SmartThings CLI

Because Developwer Workspace doesn't support a Device Preference, Developers need to use SmartThings CLI for creating Explicit Device Preferences, for adding "Device Prefereces" to "Device Profiles".
Please visit SmartThings Developers website for more details.

How to add Device Preferences to direct connected devices

This is an examples for adding "reverse" preference - one of standard device preferences - to switch_example project.

Deploy to test device on Developer Workspace

NOTE: Please use iot-core version v1.8.7 or above.

You need to do everything which is mentioned at getting started document before adding Device Prefereces to your device. Your device need to be deployed to test state.

Update Device Profile with using CLI

• Onboard your device with My Testing Devices menu.
• Get Device Id from CLI.

  user@system:~$ smartthings devices
  ────────────────────────────────────────────────────────────────────────────────────────────
   #   Label                  Name                     Type    Device Id
  ────────────────────────────────────────────────────────────────────────────────────────────
   1   SwitchWithPreferences  switchWithPreferences    MQTT    oooooooo-0000-oooo-0000-oooooooooooo

• Get Profile Id from CLI. You can find it from Profile Id field. (12345678-abcd-abcd-abcd-1234567890ab in this example)

  user@system:~$ smartthings devices {Device Id}
  Main Info
  ─────────────────────────────────────────────────────────
   Label              SwitchWithPreferences
   Name               switchWithPreferences
   Id                 oooooooo-0000-oooo-0000-oooooooooooo
   Type               MQTT
   Manufacturer Code  0ABC
   Location Id        aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
   Room Id            aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
   Profile Id         12345678-abcd-abcd-abcd-1234567890ab
   Capabilities       healthCheck
                      switch
  ─────────────────────────────────────────────────────────

• Download Device profile yaml or json file. (it's depend on output file extention)

  user@system:~$ smartthings deviceprofiles {Profile Id} -o {filename}.yaml

• Fill preferences section of the downloaded file. (preferenceId, explicit field)
  • Before

    id: ...
    name: switchWithPreferences
    metadata:
    ...
    preferences:[]
    components:
    

  • After

    id: ...
    name: switchWithPreferences
    metadata:
    ...
    preferences:
      - preferenceId: reverse
        explicit: true
    components:
    

• Update Device profile with edited yaml or json file.

  user@system:~$ smartthings deviceprofiles:update {Profiles Id} -i {filename}.yaml

• Write Device Preference handler callback function to your device app.
  As you can see light_example code block, You can get message from iot-core with iot_noti_cb. IOT_NOTI_TYPE_PREFERENCE_UPDATED message would be called when after connect to cloud and whenever the value has changed. Below is a simple handler example which prints the "reverse" preference's boolean value.

  static void iot_noti_cb(iot_noti_data_t *noti_data, void *noti_usr_data)
  {
      printf("Notification message received\n");
  
      if (noti_data->type == IOT_NOTI_TYPE_DEV_DELETED) {
          printf("[device deleted]\n");
      } else if (noti_data->type == IOT_NOTI_TYPE_RATE_LIMIT) {
          printf("[rate limit] Remaining time:%d, sequence number:%d\n",
                 noti_data->raw.rate_limit.remainingTime, noti_data->raw.rate_limit.sequenceNumber);
      } else if(noti_data->type == IOT_NOTI_TYPE_PREFERENCE_UPDATED) {
      	for (int i = 0; i < noti_data->raw.preferences.preferences_num; i++) {
              if (!strncmp(noti_data->raw.preferences.preferences_data[i].preference_name, "reverse", strlen("reverse"))) {
                  printf("set [reverse] as %s\n", noti_data->raw.preferences.preferences_data[i].preference_data.boolean ? "true" : "false");
                  break;
              }
    	  }
      }
  }