AWS IoT Wireless

(1)

AWS IoT Wireless

API Reference

API Version 2020-11-22

(2)

AWS IoT Wireless: API Reference

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

Welcome

AWS IoT Wireless provides bi-directional communication between internet-connected wireless devices and the AWS Cloud. To onboard both LoRaWAN and Sidewalk devices to AWS IoT, use the IoT Wireless API. These wireless devices use the Low Power Wide Area Networking (LPWAN) communication protocol to communicate with AWS IoT.

Using the API, you can perform create, read, update, and delete operations for your wireless devices, gateways, destinations, and proﬁles. After onboarding your devices, you can use the API operations to set log levels and monitor your devices with CloudWatch.

You can also use the API operations to create multicast groups and schedule a multicast session for sending a downlink message to devices in the group. By using Firmware Updates Over-The-Air (FUOTA) API operations, you can create a FUOTA task and schedule a session to update the ﬁrmware of individual devices or an entire group of devices in a multicast group.

This document was last published on March 6, 2022.

(20)

Actions

The following actions are supported:

• AssociateAwsAccountWithPartnerAccount (p. 5)

• AssociateMulticastGroupWithFuotaTask (p. 8)

• AssociateWirelessDeviceWithFuotaTask (p. 10)

• AssociateWirelessDeviceWithMulticastGroup (p. 12)

• AssociateWirelessDeviceWithThing (p. 14)

• AssociateWirelessGatewayWithCertiﬁcate (p. 16)

• AssociateWirelessGatewayWithThing (p. 19)

• CancelMulticastGroupSession (p. 21)

• CreateDestination (p. 23)

• CreateDeviceProﬁle (p. 27)

• CreateFuotaTask (p. 30)

• CreateMulticastGroup (p. 34)

• CreateServiceProﬁle (p. 37)

• CreateWirelessDevice (p. 40)

• CreateWirelessGateway (p. 44)

• CreateWirelessGatewayTask (p. 47)

• CreateWirelessGatewayTaskDeﬁnition (p. 50)

• DeleteDestination (p. 54)

• DeleteDeviceProﬁle (p. 56)

• DeleteFuotaTask (p. 58)

• DeleteMulticastGroup (p. 60)

• DeleteQueuedMessages (p. 62)

• DeleteServiceProﬁle (p. 64)

• DeleteWirelessDevice (p. 66)

• DeleteWirelessGateway (p. 68)

• DeleteWirelessGatewayTask (p. 70)

• DeleteWirelessGatewayTaskDeﬁnition (p. 72)

• DisassociateAwsAccountFromPartnerAccount (p. 74)

• DisassociateMulticastGroupFromFuotaTask (p. 76)

• DisassociateWirelessDeviceFromFuotaTask (p. 78)

• DisassociateWirelessDeviceFromMulticastGroup (p. 80)

• DisassociateWirelessDeviceFromThing (p. 82)

• DisassociateWirelessGatewayFromCertiﬁcate (p. 84)

• DisassociateWirelessGatewayFromThing (p. 86)

• GetDestination (p. 88)

• GetDeviceProﬁle (p. 91)

• GetFuotaTask (p. 94)

• GetLogLevelsByResourceTypes (p. 97)

• GetMulticastGroup (p. 100)

• GetMulticastGroupSession (p. 103)

(21)

• GetNetworkAnalyzerConﬁguration (p. 105)

• GetPartnerAccount (p. 108)

• GetResourceEventConﬁguration (p. 110)

• GetResourceLogLevel (p. 113)

• GetServiceEndpoint (p. 115)

• GetServiceProﬁle (p. 117)

• GetWirelessDevice (p. 120)

• GetWirelessDeviceStatistics (p. 124)

• GetWirelessGateway (p. 127)

• GetWirelessGatewayCertiﬁcate (p. 130)

• GetWirelessGatewayFirmwareInformation (p. 132)

• GetWirelessGatewayStatistics (p. 134)

• GetWirelessGatewayTask (p. 137)

• GetWirelessGatewayTaskDeﬁnition (p. 140)

• ListDestinations (p. 143)

• ListDeviceProﬁles (p. 145)

• ListFuotaTasks (p. 147)

• ListMulticastGroups (p. 149)

• ListMulticastGroupsByFuotaTask (p. 151)

• ListPartnerAccounts (p. 154)

• ListQueuedMessages (p. 156)

• ListServiceProﬁles (p. 159)

• ListTagsForResource (p. 161)

• ListWirelessDevices (p. 163)

• ListWirelessGateways (p. 166)

• ListWirelessGatewayTaskDeﬁnitions (p. 169)

• PutResourceLogLevel (p. 172)

• ResetAllResourceLogLevels (p. 174)

• ResetResourceLogLevel (p. 176)

• SendDataToMulticastGroup (p. 178)

• SendDataToWirelessDevice (p. 181)

• StartBulkAssociateWirelessDeviceWithMulticastGroup (p. 184)

• StartBulkDisassociateWirelessDeviceFromMulticastGroup (p. 187)

• StartFuotaTask (p. 190)

• StartMulticastGroupSession (p. 192)

• TagResource (p. 194)

• TestWirelessDevice (p. 196)

• UntagResource (p. 198)

• UpdateDestination (p. 200)

• UpdateFuotaTask (p. 203)

• UpdateLogLevelsByResourceTypes (p. 206)

• UpdateMulticastGroup (p. 209)

• UpdateNetworkAnalyzerConﬁguration (p. 212)

• UpdatePartnerAccount (p. 215)

• UpdateResourceEventConﬁguration (p. 217)

• UpdateWirelessDevice (p. 220)

(22)

• UpdateWirelessGateway (p. 223)

(23)

AssociateAwsAccountWithPartnerAccount

Associates a partner account with your AWS account.

Request Syntax

POST /partner-accounts HTTP/1.1 Content-type: application/json { "ClientRequestToken": "string", "Sidewalk": {

"AmazonId": "string",

"AppServerPrivateKey": "string"

},

"Tags": [ {

"Key": "string", "Value": "string"

} ] }

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

ClientRequestToken (p. 5)

Each resource must have a unique client request token. If you try to create a new resource with the same token as a resource that already exists, an exception occurs. If you omit this value, AWS SDKs will automatically generate a unique client request.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: ^[a-zA-Z0-9-_]+$

Required: No Sidewalk (p. 5)

The Sidewalk account credentials.

Type: SidewalkAccountInfo (p. 276) object Required: Yes

Tags (p. 5)

The tags to attach to the speciﬁed resource. Tags are metadata that you can use to manage a resource.

Type: Array of Tag (p. 284) objects

(24)

Response Syntax

Array Members: Minimum number of 0 items. Maximum number of 200 items.

Required: No

Response Syntax

HTTP/1.1 200

Content-type: application/json {

"Arn": "string", "Sidewalk": {

"AmazonId": "string",

"AppServerPrivateKey": "string"

} }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

Arn (p. 6)

The Amazon Resource Name of the resource.

Type: String Sidewalk (p. 6)

The Sidewalk account credentials.

Type: SidewalkAccountInfo (p. 276) object

Errors

For information about the errors that are common to all actions, see Common Errors (p. 299).

AccessDeniedException

User does not have permission to perform this action.

HTTP Status Code: 403 ConﬂictException

Adding, updating, or deleting the resource can cause an inconsistent state.

HTTP Status Code: 409 InternalServerException

An unexpected error occurred while processing a request.

HTTP Status Code: 500 ResourceNotFoundException

Resource does not exist.

(25)

See Also

HTTP Status Code: 404 ThrottlingException

The request was denied because it exceeded the allowed API request rate.

HTTP Status Code: 429 ValidationException

The input did not meet the speciﬁed constraints.

HTTP Status Code: 400

AssociateMulticastGroupWithFuotaTask

Associate a multicast group with a FUOTA task.

Request Syntax

PUT /fuota-tasks/Id/multicast-group HTTP/1.1 Content-type: application/json

{ "MulticastGroupId": "string"

}

URI Request Parameters

The request uses the following URI parameters.

Id (p. 8)

The ID of a FUOTA task.

Length Constraints: Maximum length of 256.

Required: Yes

Request Body

MulticastGroupId (p. 8)

The ID of the multicast group.

Type: String

Required: Yes

Response Syntax

HTTP/1.1 204

Response Elements

If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Errors

(27)

See Also

AssociateWirelessDeviceWithFuotaTask

Associate a wireless device with a FUOTA task.

Request Syntax

PUT /fuota-tasks/Id/wireless-device HTTP/1.1 Content-type: application/json

{ "WirelessDeviceId": "string"

}

URI Request Parameters

Id (p. 10)

Required: Yes

Request Body

WirelessDeviceId (p. 10)

The ID of the wireless device.

Type: String

Required: Yes

Response Syntax

HTTP/1.1 204

Response Elements

Errors

(29)

See Also

AssociateWirelessDeviceWithMulticastGroup

Associates a wireless device with a multicast group.

Request Syntax

PUT /multicast-groups/Id/wireless-device HTTP/1.1 Content-type: application/json

{ "WirelessDeviceId": "string"

}

URI Request Parameters

Id (p. 12)

Required: Yes

Request Body

WirelessDeviceId (p. 12)

The ID of the wireless device.

Type: String

Required: Yes

Response Syntax

HTTP/1.1 204

Response Elements

Errors

(31)

See Also

AssociateWirelessDeviceWithThing

Associates a wireless device with a thing.

Request Syntax

PUT /wireless-devices/Id/thing HTTP/1.1 Content-type: application/json

{ "ThingArn": "string"

}

URI Request Parameters

Id (p. 14)

The ID of the resource to update.

Required: Yes

Request Body

ThingArn (p. 14)

The ARN of the thing to associate with the wireless device.

Type: String Required: Yes

Response Syntax

HTTP/1.1 204

Response Elements

Errors

(33)

See Also

AssociateWirelessGatewayWithCertiﬁcate

Associates a wireless gateway with a certiﬁcate.

Request Syntax

PUT /wireless-gateways/Id/certificate HTTP/1.1 Content-type: application/json

{

"IotCertificateId": "string"

}

URI Request Parameters

Id (p. 16)

Required: Yes

Request Body

IotCertiﬁcateId (p. 16)

The ID of the certiﬁcate to associate with the wireless gateway.

Type: String

Required: Yes

Response Syntax

HTTP/1.1 200

Content-type: application/json { "IotCertificateId": "string"

}

Response Elements

(35)

Errors

IotCertiﬁcateId (p. 16)

The ID of the certiﬁcate associated with the wireless gateway.

Type: String

Errors

AssociateWirelessGatewayWithThing

Associates a wireless gateway with a thing.

Request Syntax

PUT /wireless-gateways/Id/thing HTTP/1.1 Content-type: application/json

{ "ThingArn": "string"

}

URI Request Parameters

Id (p. 19)

Required: Yes

Request Body

ThingArn (p. 19)

The ARN of the thing to associate with the wireless gateway.

Type: String Required: Yes

Response Syntax

HTTP/1.1 204

Response Elements

Errors

(38)

See Also

CancelMulticastGroupSession

Cancels an existing multicast group session.

Request Syntax

DELETE /multicast-groups/Id/session HTTP/1.1

URI Request Parameters

Id (p. 21)

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 204

Response Elements

Errors

(40)

See Also

ResourceNotFoundException Resource does not exist.

CreateDestination

Creates a new destination that maps a device message to an AWS IoT rule.

Request Syntax

POST /destinations HTTP/1.1 Content-type: application/json {

"ClientRequestToken": "string", "Description": "string", "Expression": "string", "ExpressionType": "string", "Name": "string",

"RoleArn": "string", "Tags": [

{

} ]}

URI Request Parameters

Request Body

Type: String

Required: No Description (p. 23)

The description of the new resource.

Type: String

Required: No Expression (p. 23)

The rule name or topic rule to send messages to.

(42)

Response Syntax

Type: String

Required: Yes ExpressionType (p. 23)

The type of value in Expression.

Type: String

Valid Values: RuleName | MqttTopic Required: Yes

Name (p. 23)

The name of the new resource.

Type: String

Pattern: [a-zA-Z0-9-_]+

Required: Yes RoleArn (p. 23)

The ARN of the IAM Role that authorizes the destination.

Type: String

Required: Yes Tags (p. 23)

The tags to attach to the new destination. Tags are metadata that you can use to manage a resource.

Required: No

Response Syntax

HTTP/1.1 201

Content-type: application/json {

"Arn": "string", "Name": "string"

}

Response Elements

(43)

Errors

Arn (p. 24)

The Amazon Resource Name of the new resource.

Type: String Name (p. 24)

Type: String

Pattern: [a-zA-Z0-9-_]+

Errors

CreateDeviceProﬁle

Creates a new device proﬁle.

Request Syntax

POST /device-profiles HTTP/1.1 Content-type: application/json { "ClientRequestToken": "string", "LoRaWAN": {

"ClassBTimeout": number, "ClassCTimeout": number,

"FactoryPresetFreqsList": [ number ], "MacVersion": "string",

"MaxDutyCycle": number, "MaxEirp": number, "PingSlotDr": number, "PingSlotFreq": number, "PingSlotPeriod": number, "RegParamsRevision": "string", "RfRegion": "string",

"RxDataRate2": number, "RxDelay1": number, "RxDrOffset1": number, "RxFreq2": number,

"Supports32BitFCnt": boolean, "SupportsClassB": boolean, "SupportsClassC": boolean, "SupportsJoin": boolean },

"Name": "string", "Tags": [ {

} ] }

URI Request Parameters

Request Body

Type: String

(46)

Response Syntax

Required: No LoRaWAN (p. 27)

The device proﬁle information to use to create the device proﬁle.

Type: LoRaWANDeviceProﬁle (p. 242) object Required: No

Name (p. 27)

Type: String

Required: No Tags (p. 27)

The tags to attach to the new device proﬁle. Tags are metadata that you can use to manage a resource.

Required: No

Response Syntax

HTTP/1.1 201

Content-type: application/json { "Arn": "string",

"Id": "string"

}

Response Elements

Arn (p. 28)

Type: String Id (p. 28)

The ID of the new device proﬁle.

Type: String

(47)

Errors

CreateFuotaTask

Creates a FUOTA task.

Request Syntax

POST /fuota-tasks HTTP/1.1 Content-type: application/json { "ClientRequestToken": "string", "Description": "string",

"FirmwareUpdateImage": "string", "FirmwareUpdateRole": "string", "LoRaWAN": {

"RfRegion": "string"

},

} ]}

URI Request Parameters

Request Body

Type: String

The description of the new resource.

Type: String

Required: No

(49)

Response Syntax

FirmwareUpdateImage (p. 30)

The S3 URI points to a ﬁrmware update image that is to be used with a FUOTA task.

Type: String

Required: Yes

FirmwareUpdateRole (p. 30)

The ﬁrmware update role that is to be used with a FUOTA task.

Type: String

Required: Yes LoRaWAN (p. 30)

The LoRaWAN information used with a FUOTA task.

Type: LoRaWANFuotaTask (p. 246) object Required: No

Name (p. 30)

The name of a FUOTA task.

Type: String

The tag to attach to the speciﬁed resource. Tags are metadata that you can use to manage a resource.

Required: No

Response Syntax

HTTP/1.1 201

"Id": "string"

}

Response Elements

(50)

Errors

Arn (p. 31)

The arn of a FUOTA task.

Type: String

Id (p. 31)

Type: String

Errors

CreateMulticastGroup

Creates a multicast group.

Request Syntax

POST /multicast-groups HTTP/1.1 Content-type: application/json { "ClientRequestToken": "string", "Description": "string", "LoRaWAN": {

"DlClass": "string", "RfRegion": "string"

},

} ]}

URI Request Parameters

Request Body

Type: String

The description of the multicast group.

Type: String

The LoRaWAN information that is to be used with the multicast group.

(53)

Response Syntax

Type: LoRaWANMulticast (p. 257) object Required: Yes

Name (p. 34)

The name of the multicast group.

Type: String

The tag to attach to the speciﬁed resource. Tags are metadata that you can use to manage a resource.

Required: No

Response Syntax

HTTP/1.1 201

"Id": "string"

}

Response Elements

Arn (p. 35)

The arn of the multicast group.

Type: String

Id (p. 35)

Type: String

Errors

(54)

See Also

CreateServiceProﬁle

Creates a new service proﬁle.

Request Syntax

POST /service-profiles HTTP/1.1 Content-type: application/json {

"ClientRequestToken": "string", "LoRaWAN": {

"AddGwMetadata": boolean },

} ]}

URI Request Parameters

Request Body

Type: String

The service proﬁle information to use to create the service proﬁle.

Type: LoRaWANServiceProﬁle (p. 262) object Required: No

Name (p. 37)

Type: String

(56)

Response Syntax

The tags to attach to the new service proﬁle. Tags are metadata that you can use to manage a resource.

Required: No

Response Syntax

HTTP/1.1 201

"Id": "string"

}

Response Elements

Arn (p. 38)

Type: String Id (p. 38)

The ID of the new service proﬁle.

Type: String

Errors

(57)

See Also

AWS IoT Wireless

AWS IoT Wireless

API Reference

API Version 2020-11-22

AWS IoT Wireless: API Reference

Table of Contents

Welcome

Actions

AssociateAwsAccountWithPartnerAccount

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

AssociateMulticastGroupWithFuotaTask

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

AssociateWirelessDeviceWithFuotaTask

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

AssociateWirelessDeviceWithMulticastGroup

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

AssociateWirelessDeviceWithThing

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

AssociateWirelessGatewayWithCertiﬁcate

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

AssociateWirelessGatewayWithThing

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CancelMulticastGroupSession

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreateDestination

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also