Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Penyiapan yang dipandu pengguna untuk onboard dan mengoperasikan perangkat
<a name="managedintegrations-sdk-v2-cookbook-ugs"></a>

Siapkan perangkat Anda untuk dionboard ke hub Integrasi Terkelola dengan membuat hal terkelola dan menghubungkannya ke hub Anda. Bagian ini menjelaskan langkah-langkah untuk menyelesaikan proses orientasi perangkat menggunakan pengaturan yang dipandu pengguna.

## Prasyarat
<a name="managedintegrations-sdk-v2-cookbook-ugs-prereq"></a>

Selesaikan langkah-langkah ini sebelum mencoba untuk onboard perangkat:
+ Mengonboard perangkat hub ke hub Integrasi Terkelola.
+ Instal versi terbaru AWS CLI dari Referensi [AWS CLI Perintah Integrasi Terkelola](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/)
+ Berlangganan pemberitahuan acara [DEVICE\_DISCOVERY\_STATUS](managedintegrations-notifications.md#managedintegrations-notification-setup).

**Topics**
+ [Prasyarat](#managedintegrations-sdk-v2-cookbook-ugs-prereq)
+ [Prasyarat: Aktifkan mode pemasangan pada perangkat Z Wave Anda](#managedintegrations-sdk-v2-cookbook-pairing-mode)
+ [Langkah 1: Mulai penemuan perangkat](#managedintegrations-sdk-v2-cookbook-device-discovery)
+ [Langkah 2: Kueri ID pekerjaan penemuan](#managedintegrations-sdk-v2-cookbook-query-discovery)
+ [Langkah 3: Buat hal yang dikelola untuk perangkat Anda](#managedintegrations-sdk-v2-cookbook-ugs-managed-thing)
+ [Langkah 4: Kueri hal yang dikelola](#managedintegrations-sdk-v2-cookbook-query-managed-thing)
+ [Langkah 5: Dapatkan kemampuan hal yang dikelola](#managedintegrations-sdk-v2-cookbook-check-device-capabilties)
+ [Langkah 6: Kirim perintah ke hal yang dikelola](#managedintegrations-sdk-v2-cookbook-ugs-control-device)
+ [Langkah 7: Periksa status hal yang dikelola](#managedintegrations-sdk-v2-cookbook-ugs-device-state)
+ [Langkah 8: Hapus hal yang dikelola dari hub Anda](#managedintegrations-sdk-v2-cookbook-ugs-clean-up)

## Prasyarat: Aktifkan mode pemasangan pada perangkat Z Wave Anda
<a name="managedintegrations-sdk-v2-cookbook-pairing-mode"></a>

Aktifkan mode pemasangan pada Z-wave perangkat. Mode pemasangan dapat bervariasi untuk setiap Z-Wave perangkat, jadi lihat instruksi perangkat untuk mengatur mode pemasangan dengan benar. Biasanya tombol yang harus ditekan pengguna. 

## Langkah 1: Mulai penemuan perangkat
<a name="managedintegrations-sdk-v2-cookbook-device-discovery"></a>

Mulai penemuan perangkat untuk hub Anda untuk mendapatkan ID pekerjaan penemuan yang digunakan untuk onboard perangkat Anda.

**Untuk memulai penemuan perangkat**
+ Gunakan perintah [start-device-discovery](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/start-device-discovery.html) untuk mendapatkan ID pekerjaan penemuan.

  **start-device-discoverycontoh**

  ```
  #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}} \
  ```

  **Tanggapan:**

  ```
  {
        "Id": {{DISCOVERY_JOB_ID}},
        "StartedAt": "2025-06-03T14:43:12.726000-07:00"
    }
  ```
**catatan**  
Ada perintah terpisah untuk Z-wave dan perangkat Zigbee.

  *Untuk informasi selengkapnya, lihat API [start-device-discovery](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/start-device-discovery.html) di Referensi Perintah Integrasi Terkelola. AWS CLI *

## Langkah 2: Kueri ID pekerjaan penemuan
<a name="managedintegrations-sdk-v2-cookbook-query-discovery"></a>

Gunakan `list-discovered-devices` perintah untuk mendapatkan materi otentikasi perangkat Anda.

**Untuk menanyakan ID pekerjaan penemuan Anda**
+ Gunakan ID pekerjaan penemuan dengan perintah list-discovered-devices untuk mendapatkan materi otentikasi perangkat Anda.

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

**Tanggapan:**

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

### Isi Merek dan Model untuk perangkat yang ditemukan
<a name="managedintegrations-sdk-v2-cookbook-brand-model"></a>

Selama penemuan perangkat, perangkat yang ditemukan dapat secara opsional melaporkan informasi merek dan model melalui cluster Matter Basic Information. Nilai-nilai ini kemudian dikembalikan dalam [ListDiscoveredDevices](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListDiscoveredDevices.html#API_ListDiscoveredDevices_ResponseSyntax)dan [ListManagedThings](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListManagedThings.html#API_ListManagedThings_ResponseSyntax)tanggapan.

Laporkan klaster Informasi Dasar (cluster`0x0028`) pada titik akhir root perangkat (`0`) dan peta:
+ `VendorName`(atribut`0x0001`) → `Brand`
+ `ProductName`(atribut`0x0003`) → `Model`

Contoh berikut menunjukkan cara melaporkan cluster Informasi Dasar pada titik akhir root:

```
"endpoints": [{
    "id": "0",
    "clusters": [{
        "id": "0x0028",
        "attributes": [{
            "id": "0x0001",
            "value": "ExampleBrand"
        }, {
            "id": "0x0003",
            "value": "ExampleModel-X1"
        }]
    }]
}]
```

Kedua nilai adalah string dengan panjang maksimum 32 karakter. Jika cluster Informasi Dasar atau salah satu atribut tidak dilaporkan, bidang yang sesuai dihilangkan dari respons.

## Langkah 3: Buat hal yang dikelola untuk perangkat Anda
<a name="managedintegrations-sdk-v2-cookbook-ugs-managed-thing"></a>

Gunakan `create-managed-thing` perintah untuk membuat hal yang dikelola untuk perangkat Anda. Setiap perangkat membutuhkan hal yang dikelola sendiri. 

**Untuk membuat hal yang dikelola**
+ Gunakan `create-managed-thing` perintah untuk membuat hal yang dikelola untuk perangkat Anda.

  **create-managed-thingcontoh**

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

  **Tanggapan:**

  ```
  {    
      "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"
    }
  ```

  *Untuk informasi selengkapnya, lihat perintah [create-managed-thing di Referensi Perintah Integrasi Terkelola](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/create-managed-thing.html). AWS CLI *

## Langkah 4: Kueri hal yang dikelola
<a name="managedintegrations-sdk-v2-cookbook-query-managed-thing"></a>

Anda dapat memeriksa apakah hal yang dikelola diaktifkan dengan menggunakan `get-managed-thing` perintah. 

**Untuk menanyakan hal yang dikelola**
+ Gunakan `get-managed-thing` perintah untuk memeriksa apakah status penyediaan hal yang dikelola disetel ke. `ACTIVATED` Untuk informasi selengkapnya tentang status penyediaan, lihat Penyediaan [Perangkat](https://docs.aws.amazon.com/iot-mi/latest/devguide/device-provisioning.html).

  **get-managed-thingcontoh**

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

  **Tanggapan:**

  ```
  {
        "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": {}
    }
  ```

  *Untuk informasi selengkapnya, lihat perintah [get-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing.html) di Referensi Perintah Integrasi Terkelola. AWS CLI *

## Langkah 5: Dapatkan kemampuan hal yang dikelola
<a name="managedintegrations-sdk-v2-cookbook-check-device-capabilties"></a>

Anda dapat melihat daftar tindakan yang tersedia dari hal terkelola dengan menggunakan`get-managed-thing-capabiltiies`. 

**Untuk mendapatkan kemampuan perangkat**
+ Gunakan `get-managed-thing-capabilities` perintah untuk mendapatkan ID endpoint. Perhatikan juga daftar tindakan yang mungkin.

  **get-managed-thing-capabilitiescontoh**

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

  **Tanggapan:**

  ```
  {
        "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"
                            ],
                            ...
    }
  ```

  *Untuk informasi selengkapnya, lihat perintah [get-managed-thing-abilities](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing-capabilities.html) di Referensi Perintah Integrasi Terkelola. AWS CLI*

## Langkah 6: Kirim perintah ke hal yang dikelola
<a name="managedintegrations-sdk-v2-cookbook-ugs-control-device"></a>

Anda dapat menggunakan perintah send-managed-thing-command untuk mengirim perintah toggle action ke managed thing Anda. 

**Kirim perintah ke hal yang dikelola menggunakan tindakan sakelar.**
+ Gunakan `send-managed-thing-command` perintah untuk mengirim perintah toggle action.

  **send-managed-thing-commandcontoh**

  ```
  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}}
  ```
**catatan**  
Contoh ini menggunakan jq cli tetapi Anda juga dapat meneruskan seluruh string `endpointId`

  **Tanggapan:**

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

  *Untuk informasi selengkapnya, lihat perintah [send-managed-thing-command di Referensi Perintah Integrasi](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/send-managed-thing-command.html) Terkelola. AWS CLI *

## Langkah 7: Periksa status hal yang dikelola
<a name="managedintegrations-sdk-v2-cookbook-ugs-device-state"></a>

Periksa status hal yang dikelola untuk memvalidasi tindakan sakelar berhasil.

**Untuk memeriksa status perangkat yang dikelola**
+ Gunakan `get-managed-thing-state` perintah untuk memvalidasi tindakan toggle berhasil.

  **get-managed-thing-statecontoh**

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

  **Tanggapan:**

  ```
  {
        "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"
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }
  ```

  *Untuk informasi selengkapnya, lihat perintah [get-managed-thing-state](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing-state.html) di Referensi Perintah Integrasi Terkelola. AWS CLI*

## Langkah 8: Hapus hal yang dikelola dari hub Anda
<a name="managedintegrations-sdk-v2-cookbook-ugs-clean-up"></a>

Bersihkan hub Anda dengan menghapus hal yang dikelola.

**Untuk menghapus hal yang dikelola**
+ Gunakan perintah [delete-managed-thing untuk menghapus hal yang](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/delete-managed-thing.html) dikelola. 

  **delete-managed-thingcontoh**

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

  *Untuk informasi selengkapnya, lihat perintah [delete-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/delete-managed-thing.html) di Referensi Perintah Integrasi Terkelola. AWS CLI *
**catatan**  
Jika perangkat macet dalam `DELETE_IN_PROGRESS` keadaan, tambahkan `--force` bendera ke `delete-managed-thing` perintah.
**catatan**  
Untuk Z-wave perangkat, Anda harus meletakkan perangkat ke mode berpasangan setelah menjalankan perintah.