기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 디바이스 온보딩 및 운영을 위한 사용자 안내 설정
<a name="managedintegrations-sdk-v2-cookbook-ugs"></a>

허브에 연결하는 관리형 사물을 생성하여 관리형 통합 허브에 온보딩되도록 디바이스를 설정합니다. 이 섹션에서는 사용자 안내 설정을 사용하여 디바이스 온보딩 프로세스를 완료하는 단계를 설명합니다.

## 사전 조건
<a name="managedintegrations-sdk-v2-cookbook-ugs-prereq"></a>

디바이스 온보딩을 시도하기 전에 다음 단계를 완료합니다.
+ 허브 디바이스를 관리형 통합 허브에 온보딩합니다.
+ [관리형 통합 AWS CLI 명령 참조](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/) AWS CLI 에서의 최신 버전 설치
+ [DEVICE\$1DISCOVERY-STATUS](managedintegrations-notifications.md#managedintegrations-notification-setup) 이벤트 알림을 구독합니다.

**Topics**
+ [사전 조건](#managedintegrations-sdk-v2-cookbook-ugs-prereq)
+ [사전 조건: Z Wave 디바이스에서 페어링 모드 활성화](#managedintegrations-sdk-v2-cookbook-pairing-mode)
+ [1단계: 디바이스 검색 시작](#managedintegrations-sdk-v2-cookbook-device-discovery)
+ [2단계: 검색 작업 ID 쿼리](#managedintegrations-sdk-v2-cookbook-query-discovery)
+ [3단계: 디바이스에 대한 관리형 사물 생성](#managedintegrations-sdk-v2-cookbook-ugs-managed-thing)
+ [4단계: 관리형 사물 쿼리](#managedintegrations-sdk-v2-cookbook-query-managed-thing)
+ [5단계: 관리형 사물 기능 가져오기](#managedintegrations-sdk-v2-cookbook-check-device-capabilties)
+ [6단계: 관리형 사물에 명령 전송](#managedintegrations-sdk-v2-cookbook-ugs-control-device)
+ [7단계: 관리형 사물 상태 확인](#managedintegrations-sdk-v2-cookbook-ugs-device-state)
+ [8단계: 허브에서 관리형 사물 제거](#managedintegrations-sdk-v2-cookbook-ugs-clean-up)

## 사전 조건: Z Wave 디바이스에서 페어링 모드 활성화
<a name="managedintegrations-sdk-v2-cookbook-pairing-mode"></a>

Z파 디바이스에서 페어링 모드를 활성화합니다. 페어링 모드는 Z-Wave 디바이스마다 다를 수 있으므로 페어링 모드를 올바르게 설정하려면 디바이스의 지침을 참조하세요. 일반적으로 사용자가 눌러야 하는 버튼입니다.

## 1단계: 디바이스 검색 시작
<a name="managedintegrations-sdk-v2-cookbook-device-discovery"></a>

허브에 대한 디바이스 검색을 시작하여 디바이스를 온보딩하는 데 사용되는 검색 작업 ID를 가져옵니다.

**디바이스 검색을 시작하려면**
+ [start-device-discovery](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/start-device-discovery.html) 명령을 사용하여 검색 작업 ID를 가져옵니다.

  **start-device-discovery 예**

  ```
  #For Zigbee
    aws iot-managed-integrations start-device-discovery --discovery-type ZIGBEE \
    --controller-identifier HUB_MANAGED_THING_ID
    
    #For Zwave
    aws iot-managed-integrations start-device-discovery --discovery-type ZWAVE \
    --controller-identifier HUB_MANAGED_THING \
    --authentication-material-type ZWAVE_INSTALL_CODE \
    --authentication-material 13333
    
    #For Cloud
    aws iot-managed-integrations start-device-discovery --discovery-type CLOUD \
    --account-association-id C2C_ASSOCIATION_ID \
    
    #For Custom
    aws iot-managed-thing start-device-discovery --discovery-type CUSTOM \
    --controller-identifier HUB_MANAGED_THING_ID \
    --custom-protocol-detail NAME : NON_EMPTY_STRING \
  ```

  **응답**:

  ```
  {
        "Id": DISCOVERY_JOB_ID,
        "StartedAt": "2025-06-03T14:43:12.726000-07:00"
    }
  ```
**참고**  
Z-wave 및 Zigbee 디바이스에는 별도의 명령이 있습니다.

  자세한 내용은 관리형 통합 명령 참조의 [start-device-discovery](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/start-device-discovery.html) API를 AWS CLI *참조*하세요.

## 2단계: 검색 작업 ID 쿼리
<a name="managedintegrations-sdk-v2-cookbook-query-discovery"></a>

`list-discovered-devices` 명령을 사용하여 디바이스의 인증 구성 요소를 가져옵니다.

**검색 작업 ID를 쿼리하려면**
+ list-discovered-devices 명령과 함께 검색 작업 ID를 사용하여 디바이스의 인증 구성 요소를 가져옵니다.

  ```
  aws iot-managed-integrations list-discovered-devices --identifier DISCOVERY_JOB_ID
  ```

**응답**:

```
"Items": [
    {
        "DeviceTypes": [],
        "DiscoveredAt": "2025-06-03T14:43:37.619000-07:00",
        "AuthenticationMaterial": AUTHENTICATION_MATERIAL
    }
]
```

## 3단계: 디바이스에 대한 관리형 사물 생성
<a name="managedintegrations-sdk-v2-cookbook-ugs-managed-thing"></a>

`create-managed-thing` 명령을 사용하여 디바이스에 대한 관리형 사물을 생성합니다. 각 디바이스에는 자체 관리형 사물이 필요합니다.

**관리형 사물을 생성하려면**
+ `create-managed-thing` 명령을 사용하여 디바이스에 대한 관리형 사물을 생성합니다.

  **create-managed-thing 예**

  ```
  aws iot-managed-integrations create-managed-thing \
    --role  DEVICE --authentication-material-type DISCOVERED_DEVICE \
    --authentication-material "AUTHENTICATION_MATERIAL"
  ```

  **응답**:

  ```
  {    
      "Id": "DEVICE_MANAGED_THING_ID"
      "Arn": "arn:aws:iotmanagedintegrations:AWS_REGION:AWS_ACCOUNT_ID:managed-thing/DEVICE_MANAGED_THING_ID"
      "CreatedAt": "2025-06-09T13:58:52.977000+08:00"
    }
  ```

  자세한 내용은 관리형 통합 명령 참조의 [create-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/create-managed-thing.html) *명령을 참조*하세요 AWS CLI .

## 4단계: 관리형 사물 쿼리
<a name="managedintegrations-sdk-v2-cookbook-query-managed-thing"></a>

`get-managed-thing` 명령을 사용하여 관리형 사물이 활성화되었는지 확인할 수 있습니다.

**관리형 사물을 쿼리하려면**
+ `get-managed-thing` 명령을 사용하여 관리형 사물의 프로비저닝 상태가 로 설정되어 있는지 확인합니다`ACTIVATED`. 프로비저닝 상태에 대한 자세한 내용은 [디바이스 프로비저닝을 참조하세요](https://docs.aws.amazon.com/iot-mi/latest/devguide/device-provisioning.html).

  **get-managed-thing 예**

  ```
  aws iot-managed-integrations get-managed-thing \
    --identifier "DEVICE_MANAGED_THING_ID"
  ```

  **응답**:

  ```
  {
        "Id": "DEVICE_MANAGED_THING_ID",
        "Arn": "arn:aws:iotmanagedintegrations:AWS_REGION:AWS_ACCOUNT_ID:managed-thing/DEVICE_MANAGED_THING_ID,
        "Role": "DEVICE",
        "ProvisioningStatus": "ACTIVATED",
        "MacAddress": "MAC_ADDRESS",
        "ParentControllerId": "PARENT_CONTROLLER_ID",
        "CreatedAt": "2025-06-03T14:46:35.149000-07:00",
        "UpdatedAt": "2025-06-03T14:46:37.500000-07:00",
        "Tags": {}
    }
  ```

  자세한 내용은 관리형 통합 명령 참조의 [get-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing.html) *명령을 참조*하세요 AWS CLI .

## 5단계: 관리형 사물 기능 가져오기
<a name="managedintegrations-sdk-v2-cookbook-check-device-capabilties"></a>

를 사용하여 관리형 사물의 사용 가능한 작업 목록을 볼 수 있습니다`get-managed-thing-capabiltiies`.

**디바이스의 기능을 가져오려면**
+ `get-managed-thing-capabilities` 명령을 사용하여 엔드포인트 ID를 가져옵니다. 또한 가능한 작업 목록을 기록해 둡니다.

  **get-managed-thing-capabilities 예**

  ```
  aws iot-managed-integrations get-managed-thing-capabilities \
    --identifier "DEVICE_MANAGED_THING_ID"
  ```

  **응답**:

  ```
  {
        "ManagedThingId": "DEVICE_MANAGED_THING_ID",
        "CapabilityReport": {
            "version": "1.0.0",
            "nodeId": "zb.539D+4A1D",
            "endpoints": [
                {
                    "id": "1",
                    "deviceTypes": [
                        "Unknown Device"
                    ],
                    "capabilities": [
                        {
                            "id": "matter.OnOff@1.4",
                            "name": "On/Off",
                            "version": "6",
                            "properties": [
                                "OnOff",
                                "OnOff",
                                "OnTime",
                                "OffWaitTime"
                            ],
                            "actions": [
                                "Off",
                                "On",
                                "Toggle",
                                "OffWithEffect",
                                "OnWithRecallGlobalScene",
                                "OnWithTimedOff"
                            ],
                            ...
    }
  ```

  자세한 내용은 관리형 통합 명령 참조의 [get-managed-thing-capabilities](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing-capabilities.html) AWS CLI*명령을 참조*하세요.

## 6단계: 관리형 사물에 명령 전송
<a name="managedintegrations-sdk-v2-cookbook-ugs-control-device"></a>

send-managed-thing-command 명령을 사용하여 토글 작업 명령을 관리형 사물로 보낼 수 있습니다.

**토글 작업을 사용하여 관리형 사물에 명령을 보냅니다.**
+ `send-managed-thing-command` 명령을 사용하여 토글 작업 명령을 보냅니다.

  **send-managed-thing-command 예**

  ```
  json=$(jq -cr '.|@json') <<EOF
    [
      {
        "endpointId": "1",
        "capabilities": [
          {
            "id": "matter.OnOff@1.4",
            "name": "On/Off",
            "version": "1",
            "actions": [
              {
                "name": "Toggle",
                "parameters": {}
              }
            ]
          }
        ]
      }
    ]
    EOF
    aws iot-managed-integrations send-managed-thing-command \
    --managed-thing-id ${device_managed_thing_id} --endpoints ENDPOINT_ID
  ```
**참고**  
이 예제에서는 jq cli를에 사용하지만 전체 `endpointId` 문자열을 전달할 수도 있습니다.

  **응답**:

  ```
  {    
    "TraceId": TRACE_ID
    }
  ```

  자세한 내용은 관리형 통합 명령 참조의 [send-managed-thing-command](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/send-managed-thing-command.html) *명령을 참조*하세요 AWS CLI .

## 7단계: 관리형 사물 상태 확인
<a name="managedintegrations-sdk-v2-cookbook-ugs-device-state"></a>

관리형 사물의 상태를 확인하여 토글 작업이 성공했는지 확인합니다.

**관리형 사물의 디바이스 상태를 확인하려면**
+ `get-managed-thing-state` 명령을 사용하여 토글 작업이 성공했는지 확인합니다.

  **get-managed-thing-state 예**

  ```
    aws iot-managed-integrations get-managed-thing-state --managed-thing-id DEVICE_MANAGED_THING_ID
  ```

  **응답**:

  ```
  {
        "Endpoints": [
            {
                "endpointId": "1",
                "capabilities": [
                    {
                        "id": "matter.OnOff@1.4",
                        "name": "On/Off",
                        "version": "1.4",
                        "properties": [
                            {
                                "name": "OnOff",
                                "value": {
                                    "propertyValue": true,
                                    "lastChangedAt": "2025-06-03T21:50:39.886Z"
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }
  ```

  자세한 내용은 관리형 통합 명령 참조의 [get-managed-thing-state](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing-state.html) AWS CLI* 명령을 참조*하세요.

## 8단계: 허브에서 관리형 사물 제거
<a name="managedintegrations-sdk-v2-cookbook-ugs-clean-up"></a>

관리형 사물을 제거하여 허브를 정리합니다.

**관리형 사물을 삭제하려면**
+ [delete-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/delete-managed-thing.html) 명령을 사용하여 관리형 사물을 제거합니다.

  **delete-managed-thing 예**

  ```
  aws iot-managed-integrations delete-managed-thing \
    --identifier MANAGED_THING_ID
  ```

  자세한 내용은 관리형 통합 명령 참조의 [delete-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/delete-managed-thing.html) *명령을 참조*하세요 AWS CLI .
**참고**  
디바이스가 `DELETE_IN_PROGRESS` 상태로 멈춘 경우 `delete-managed-thing` 명령에 `--force` 플래그를 추가합니다.
**참고**  
Z파 디바이스의 경우 명령을 실행한 후 디바이스를 페어링 모드로 전환해야 합니다.