切换深色模式
FUOTA API
本页列出当前版本的完整方法及字段。方法通过 gRPC / gRPC-Web 调用；REST 注解不表示已部署 REST Gateway。
“必填：按业务校验”表示 proto3 未声明 required，不代表留空一定可用。UUID、EUI、权限、资源存在性与字段组合由服务端校验。嵌套结构详见页末消息结构。
FuotaService
CreateDeployment
接口名称： api.FuotaService/CreateDeployment
功能： 创建 Deployment。Create the given FUOTA deployment.
请求： api.CreateFuotaDeploymentRequest；返回： api.CreateFuotaDeploymentResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
deployment | api.FuotaDeployment | 按业务校验 | Deployment. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 ID of the created deployment. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
GetDeployment
接口名称： api.FuotaService/GetDeployment
功能： 查询 Deployment。Get the FUOTA deployment for the given ID.
请求： api.GetFuotaDeploymentRequest；返回： api.GetFuotaDeploymentResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 FUOTA Deployment ID. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
deployment | api.FuotaDeployment | 按业务校验 | FUOTA Deployment. |
created_at | google.protobuf.Timestamp | 按业务校验 | 创建时间。 Created at timestamp. |
updated_at | google.protobuf.Timestamp | 按业务校验 | 最后更新时间。 Updated at timestamp. |
started_at | google.protobuf.Timestamp | 按业务校验 | Started at timestamp. |
completed_at | google.protobuf.Timestamp | 按业务校验 | Completed at timestamp. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
UpdateDeployment
接口名称： api.FuotaService/UpdateDeployment
功能： 更新 Deployment。Update the given FUOTA deployment.
请求： api.UpdateFuotaDeploymentRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
deployment | api.FuotaDeployment | 按业务校验 | Deployment. |
返回值
无字段。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
DeleteDeployment
接口名称： api.FuotaService/DeleteDeployment
功能： 删除 Deployment。Delete the FUOTA deployment for the given ID.
请求： api.DeleteFuotaDeploymentRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 FUOTA deployment ID. |
返回值
无字段。
操作影响
此方法会删除、清空或重置对应资源/状态。调用前核对目标 ID；请勿通过重试重复执行有副作用的操作。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
StartDeployment
接口名称： api.FuotaService/StartDeployment
功能： StartDeployment。Start the FUOTA deployment.
请求： api.StartFuotaDeploymentRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 FUOTA deployment ID. |
返回值
无字段。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
ListDeployments
接口名称： api.FuotaService/ListDeployments
功能： 列出 Deployments。List the FUOTA deployments.
请求： api.ListFuotaDeploymentsRequest；返回： api.ListFuotaDeploymentsResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
limit | uint32 | 按业务校验 | 本次最多返回条数。 Max number of FUOTA deployments to return in the result-set. If not set, it will be treated as 0, and the response will only return the total_count. |
offset | uint32 | 按业务校验 | 分页起始偏移。 Offset in the result-set (for pagination). |
application_id | string | 按业务校验 | 应用 UUID。 Application ID to list the FUOTA Deployments for. This must be set, unelss tenant_id is set. |
tenant_id | string | 按业务校验 | 租户 UUID。 Tenant ID to list the FUOTA deployments for. This must be set, unless application_id is set. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
total_count | uint32 | 按业务校验 | 符合条件的总条数。 Total number of FUOTA Deployments. |
result | repeated api.FuotaDeploymentListItem | 按业务校验 | 结果列表或结果内容。 Result-test. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
AddDevices
接口名称： api.FuotaService/AddDevices
功能： 添加 Devices。Add the given DevEUIs to the FUOTA deployment.
请求： api.AddDevicesToFuotaDeploymentRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
fuota_deployment_id | string | 按业务校验 | FUOTA Deployment ID. |
dev_euis | repeated string | 按业务校验 | DevEUIs. Note that the DevEUIs must share the same device-profile as assigned to the FUOTA Deployment. |
返回值
无字段。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
RemoveDevices
接口名称： api.FuotaService/RemoveDevices
功能： 移除 Devices。Remove the given DevEUIs from the FUOTA deployment.
请求： api.RemoveDevicesFromFuotaDeploymentRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
fuota_deployment_id | string | 按业务校验 | FUOTA Deployment ID. |
dev_euis | repeated string | 按业务校验 | DevEUIs. |
返回值
无字段。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
ListDevices
接口名称： api.FuotaService/ListDevices
功能： 列出 Devices。List FUOTA Deployment devices.
请求： api.ListFuotaDeploymentDevicesRequest；返回： api.ListFuotaDeploymentDevicesResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
limit | uint32 | 按业务校验 | 本次最多返回条数。 Max number of devices to return in the result-set. If not set, it will be treated as 0, and the response will only return the total_count. |
offset | uint32 | 按业务校验 | 分页起始偏移。 Offset in the result-set (for pagination). |
fuota_deployment_id | string | 按业务校验 | FUOTA Deployment ID. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
total_count | uint32 | 按业务校验 | 符合条件的总条数。 Total number of devices. |
result | repeated api.FuotaDeploymentDeviceListItem | 按业务校验 | 结果列表或结果内容。 Result-set. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
AddGateways
接口名称： api.FuotaService/AddGateways
功能： 添加 Gateways。Add the given Gateway IDs to the FUOTA deployment. By default, ChirpStack will automatically select the minimum amount of gateways needed to cover all devices within the multicast-group. Setting the gateways manually overrides this behaviour.
请求： api.AddGatewaysToFuotaDeploymentRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
fuota_deployment_id | string | 按业务校验 | FUOTA Deployment ID. |
gateway_ids | repeated string | 按业务校验 | Gateway IDs. Note that the Gateways must be under the same tenant as the FUOTA Deployment. |
返回值
无字段。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
ListGateways
接口名称： api.FuotaService/ListGateways
功能： 列出 Gateways。List the gateways added to the FUOTA deployment.
请求： api.ListFuotaDeploymentGatewaysRequest；返回： api.ListFuotaDeploymentGatewaysResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
limit | uint32 | 按业务校验 | 本次最多返回条数。 Max number of gateways to return in the result-set. If not set, it will be treated as 0, and the response will only return the total_count. |
offset | uint32 | 按业务校验 | 分页起始偏移。 Offset in the result-set (for pagination). |
fuota_deployment_id | string | 按业务校验 | FUOTA Deployment ID. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
total_count | uint32 | 按业务校验 | 符合条件的总条数。 Total number of gateways. |
result | repeated api.FuotaDeploymentGatewayListItem | 按业务校验 | 结果列表或结果内容。 Result-set. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
RemoveGateways
接口名称： api.FuotaService/RemoveGateways
功能： 移除 Gateways。Remove the given Gateway IDs from the FUOTA deployment.
请求： api.RemoveGatewaysFromFuotaDeploymentRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
fuota_deployment_id | string | 按业务校验 | FUOTA Deployment ID. |
gateway_ids | repeated string | 按业务校验 | Gateway IDs. |
返回值
无字段。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
ListJobs
接口名称： api.FuotaService/ListJobs
功能： 列出 Jobs。List jobs for the given FUOTA deployment.
请求： api.ListFuotaDeploymentJobsRequest；返回： api.ListFuotaDeploymentJobsResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
fuota_deployment_id | string | 按业务校验 | FUOTA Deployment ID. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
jobs | repeated api.FuotaDeploymentJob | 按业务校验 | Jobs. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
嵌套消息结构
api.AddDevicesToFuotaDeploymentRequest
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
fuota_deployment_id | string | 按业务校验 | FUOTA Deployment ID. |
dev_euis | repeated string | 按业务校验 | DevEUIs. Note that the DevEUIs must share the same device-profile as assigned to the FUOTA Deployment. |
api.AddGatewaysToFuotaDeploymentRequest
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
fuota_deployment_id | string | 按业务校验 | FUOTA Deployment ID. |
gateway_ids | repeated string | 按业务校验 | Gateway IDs. Note that the Gateways must be under the same tenant as the FUOTA Deployment. |
api.CreateFuotaDeploymentRequest
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
deployment | api.FuotaDeployment | 按业务校验 | Deployment. |
api.CreateFuotaDeploymentResponse
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 ID of the created deployment. |
api.DeleteFuotaDeploymentRequest
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 FUOTA deployment ID. |
api.FuotaDeployment
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 Deployment ID. This value is automatically set on create. |
application_id | string | 按业务校验 | 应用 UUID。 Application ID. |
device_profile_id | string | 按业务校验 | 终端模版 UUID。 Device-profile ID. |
name | string | 按业务校验 | 名称。 Deployment name. |
multicast_group_type | api.MulticastGroupType {CLASS_C=0, CLASS_B=1} | 按业务校验 | Multicast-group type. |
multicast_class_c_scheduling_type | api.MulticastGroupSchedulingType {DELAY=0, GPS_TIME=1} | 按业务校验 | Multicast-group scheduling type (Class-C only). |
multicast_dr | uint32 | 按业务校验 | Multicast data-rate. |
multicast_class_b_ping_slot_periodicity | uint32 | 按业务校验 | Multicast ping-slot period (Class-B only). Valid options are: 0 - 7. Number of ping-slots per beacon-period: pingNb = 2^(7-periodicity) Periodicity: 0 = 128 ping-slots per beacon period = ~ every 1 sec Periodicity: 7 = 1 ping-slot per beacon period = ~ every 128 sec |
multicast_frequency | uint32 | 按业务校验 | Multicast frequency (Hz). |
multicast_timeout | uint32 | 按业务校验 | Multicast timeout. This defines the timeout of the multicast-session. Please refer to the Remote Multicast Setup specification as this field has a different meaning for Class-B and Class-C groups. |
calculate_multicast_timeout | bool | 按业务校验 | Calculate multicast timeout. If set to true, ChirpStack will calculate the multicast-timeout. |
unicast_max_retry_count | uint32 | 按业务校验 | The number of times ChirpStack will retry an unicast command before it considers it to be failed. |
fragmentation_fragment_size | uint32 | 按业务校验 | Fragmentation size. This defines the size of each payload fragment. Please refer to the Regional Parameters specification for the maximum payload sizes per data-rate and region. |
calculate_fragmentation_fragment_size | bool | 按业务校验 | Calculate fragmentation size. If set to true, ChirpStack will calculate the fragmentation size. |
fragmentation_redundancy_percentage | uint32 | 按业务校验 | Fragmentation redundancy percentage. The number represents the percentage (0 - 100) of redundant messages to send. |
fragmentation_session_index | uint32 | 按业务校验 | Fragmentation session index. |
fragmentation_matrix | uint32 | 按业务校验 | Fragmentation matrix. |
fragmentation_block_ack_delay | uint32 | 按业务校验 | Block ack delay. |
fragmentation_descriptor | bytes | 按业务校验 | Descriptor (4 bytes). |
request_fragmentation_session_status | api.RequestFragmentationSessionStatus {NO_REQUEST=0, AFTER_FRAGMENT_ENQUEUE=1, AFTER_SESSION_TIMEOUT=2} | 按业务校验 | Request fragmentation session status. |
payload | bytes | 按业务校验 | Payload. The FUOTA payload to send. |
on_complete_set_device_tags | map<string, string> | 按业务校验 | Set device tags on complete. |
api.FuotaDeployment.OnCompleteSetDeviceTagsEntry
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
key | string | 按业务校验 | 消息定义未补充字段说明。 |
value | string | 按业务校验 | 消息定义未补充字段说明。 |
api.FuotaDeploymentDeviceListItem
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
fuota_deployment_id | string | 按业务校验 | ID. |
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 DevEUI. |
created_at | google.protobuf.Timestamp | 按业务校验 | 创建时间。 Created at timestamp. |
completed_at | google.protobuf.Timestamp | 按业务校验 | Completed at timestamp. |
mc_group_setup_completed_at | google.protobuf.Timestamp | 按业务校验 | McGroupSetup completed at timestamp. |
mc_session_completed_at | google.protobuf.Timestamp | 按业务校验 | McSession completed at timestamp. |
frag_session_setup_completed_at | google.protobuf.Timestamp | 按业务校验 | FragSessionSetup completed at timestamp. |
frag_status_completed_at | google.protobuf.Timestamp | 按业务校验 | FragStatus completed at timestamp. |
error_msg | string | 按业务校验 | Error message. |
api.FuotaDeploymentGatewayListItem
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
fuota_deployment_id | string | 按业务校验 | ID. |
gateway_id | string | 按业务校验 | 网关 EUI。 Gateway ID. |
created_at | google.protobuf.Timestamp | 按业务校验 | 创建时间。 Created at timestamp. |
api.FuotaDeploymentJob
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
job | string | 按业务校验 | Job identifier. |
created_at | google.protobuf.Timestamp | 按业务校验 | 创建时间。 Created at. |
completed_at | google.protobuf.Timestamp | 按业务校验 | Completed at. |
max_retry_count | uint32 | 按业务校验 | Max. retry count. |
attempt_count | uint32 | 按业务校验 | Attempt count. |
scheduler_run_after | google.protobuf.Timestamp | 按业务校验 | Scheduler run after. |
warning_msg | string | 按业务校验 | Warning message. |
error_msg | string | 按业务校验 | Error message. |
api.FuotaDeploymentListItem
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 ID. |
created_at | google.protobuf.Timestamp | 按业务校验 | 创建时间。 Created at timestamp. |
updated_at | google.protobuf.Timestamp | 按业务校验 | 最后更新时间。 Updated at timestamp. |
started_at | google.protobuf.Timestamp | 按业务校验 | Started at timestamp. |
completed_at | google.protobuf.Timestamp | 按业务校验 | Completed at timestamp. |
name | string | 按业务校验 | 名称。 Name. |
application_id | string | 按业务校验 | 应用 UUID。 Application ID. |
application_name | string | 按业务校验 | Application name. |
api.GetFuotaDeploymentRequest
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 FUOTA Deployment ID. |
api.GetFuotaDeploymentResponse
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
deployment | api.FuotaDeployment | 按业务校验 | FUOTA Deployment. |
created_at | google.protobuf.Timestamp | 按业务校验 | 创建时间。 Created at timestamp. |
updated_at | google.protobuf.Timestamp | 按业务校验 | 最后更新时间。 Updated at timestamp. |
started_at | google.protobuf.Timestamp | 按业务校验 | Started at timestamp. |
completed_at | google.protobuf.Timestamp | 按业务校验 | Completed at timestamp. |
api.ListFuotaDeploymentDevicesRequest
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
limit | uint32 | 按业务校验 | 本次最多返回条数。 Max number of devices to return in the result-set. If not set, it will be treated as 0, and the response will only return the total_count. |
offset | uint32 | 按业务校验 | 分页起始偏移。 Offset in the result-set (for pagination). |
fuota_deployment_id | string | 按业务校验 | FUOTA Deployment ID. |
api.ListFuotaDeploymentDevicesResponse
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
total_count | uint32 | 按业务校验 | 符合条件的总条数。 Total number of devices. |
result | repeated api.FuotaDeploymentDeviceListItem | 按业务校验 | 结果列表或结果内容。 Result-set. |
api.ListFuotaDeploymentGatewaysRequest
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
limit | uint32 | 按业务校验 | 本次最多返回条数。 Max number of gateways to return in the result-set. If not set, it will be treated as 0, and the response will only return the total_count. |
offset | uint32 | 按业务校验 | 分页起始偏移。 Offset in the result-set (for pagination). |
fuota_deployment_id | string | 按业务校验 | FUOTA Deployment ID. |
api.ListFuotaDeploymentGatewaysResponse
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
total_count | uint32 | 按业务校验 | 符合条件的总条数。 Total number of gateways. |
result | repeated api.FuotaDeploymentGatewayListItem | 按业务校验 | 结果列表或结果内容。 Result-set. |
api.ListFuotaDeploymentJobsRequest
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
fuota_deployment_id | string | 按业务校验 | FUOTA Deployment ID. |
api.ListFuotaDeploymentJobsResponse
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
jobs | repeated api.FuotaDeploymentJob | 按业务校验 | Jobs. |
api.ListFuotaDeploymentsRequest
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
limit | uint32 | 按业务校验 | 本次最多返回条数。 Max number of FUOTA deployments to return in the result-set. If not set, it will be treated as 0, and the response will only return the total_count. |
offset | uint32 | 按业务校验 | 分页起始偏移。 Offset in the result-set (for pagination). |
application_id | string | 按业务校验 | 应用 UUID。 Application ID to list the FUOTA Deployments for. This must be set, unelss tenant_id is set. |
tenant_id | string | 按业务校验 | 租户 UUID。 Tenant ID to list the FUOTA deployments for. This must be set, unless application_id is set. |
api.ListFuotaDeploymentsResponse
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
total_count | uint32 | 按业务校验 | 符合条件的总条数。 Total number of FUOTA Deployments. |
result | repeated api.FuotaDeploymentListItem | 按业务校验 | 结果列表或结果内容。 Result-test. |
api.RemoveDevicesFromFuotaDeploymentRequest
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
fuota_deployment_id | string | 按业务校验 | FUOTA Deployment ID. |
dev_euis | repeated string | 按业务校验 | DevEUIs. |
api.RemoveGatewaysFromFuotaDeploymentRequest
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
fuota_deployment_id | string | 按业务校验 | FUOTA Deployment ID. |
gateway_ids | repeated string | 按业务校验 | Gateway IDs. |
api.StartFuotaDeploymentRequest
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 FUOTA deployment ID. |
api.UpdateFuotaDeploymentRequest
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
deployment | api.FuotaDeployment | 按业务校验 | Deployment. |