Create Firmware File¶

Create a firmware file for a product.

Operation Permissions¶

Required Authorization	Required Operation Permission
Device Management	Full Access

Request Format¶

POST https://{apigw-address}/connect-service/v2.1/ota-firmwares?action=create

Request Parameters (URI)¶

Name	Location（Path/Query）	Mandatory/Optional	Data Type	Description
orgId	Query	Mandatory	String	The organization ID which the asset belongs to. How to get orgId>>
productKey	Query	Mandatory	String	The product key.

Request Parameters (Body)¶

The format of the request body is multipart/form-data, which consists of two form-data sections:

Firmware metadata form-data
Firmware file form-data

Header of the firmware metadata form-data¶
Name	Mandatory/Optional	Data Type	Description
Content-Disposition	Mandatory	Content-Disposition: form-data; name=”metadata”	`name` is a constant that indicates the name of the metadata message.

Body of the firmware metadata form-data¶
Name	Mandatory/Optional	Data Type	Description
name	Mandatory	StringI18n	The firmware name. For more details on the structure and locales supported, see Internationalized name struct>>
version	Mandatory	String	The firmware version.
signMethod	Mandatory	String	The signature algorithm for the firmware files, supports `md5` and `sha256`.
sign	Mandatory	String	The fimware file signature.
desc	Optional	String	The firmware description.
enableVerification	Mandatory	Boolean	Specifies whether the firmware must be verified for upgrading tasks. `true`: Needs to be verified. `false`: Does not need to be verified.

Header of the firmware file form-data¶
Name	Mandatory/Optional	Data Type	Description
Content-Disposition	Mandatory	Content-Disposition: form-data; name=”file”; filename=”yourFileName”	`name` is a constant that indicates the name of the metadata message. `filename` is the filename corresponding to the firmware.

Response Parameters¶

Name	Data Type	Description
data	FirmwareCreateResult Struct	The created firmware ID. For details, see FirmwareCreateResult Struct>>

FirmwareCreateResult Struct ¶

Name	Data Type	Description
firmwareId	String	The created firmware ID.

Error Codes¶

Code	Message	Description
24601	Firmware version already exists	A firmware with this version already exists.
24602	Firmware name already exists	A firmware with this name already exists.
24603	Not allowed to create firmware concurrently	Firmware cannot be created concurrently.

Samples¶

Request Sample¶

url: https://{apigw-address}/connect-service/v2.1/ota-firmwares?action=create&orgId=yourOrgId&productKey=yourProductKey
method: POST
requestBody:
  Firmware metadata form-data:
    Header:
    Content-Disposition: form-data; name="metadata"
    Body:
    {
    "name": {
        "defaultValue": "testDefaultValue"
    },
    "version": "yourVersion",
    "signMethod": "md5",
    "sign": "7eb565583c040b76b7466af1ecb553f3",
    "enableVerification": false,
    "desc": "ota firmware"
    }

Return Sample¶

{
    "code": 0,
    "msg": "OK",
    "requestId": "9bba8197-d6d6-4fe2-a3d2-65153ab6376c",
    "data": {
        "firmwareId": "5ee0edb729b990001b9acf9a"
    }
}

Java SDK Sample¶

package com.envisioniot.enos.connect_service.ota.firmware;

import com.envision.apim.poseidon.config.PConfig;
import com.envision.apim.poseidon.core.Poseidon;
import com.envisioniot.enos.api.common.constant.common.StringI18n;
import com.envisioniot.enos.connect_service.v2_1.ota.firmware.CreateFirmwareFileRequest;
import com.envisioniot.enos.connect_service.v2_1.ota.firmware.CreateFirmwareFileResponse;
import com.envisioniot.enos.connect_service.vo.ota.SignMethod;

import java.io.File;

public class CreateFirmware {
    public static void main(String[] args) {
        final String appKey = "yourAppKey";
        final String appSecret = "yourAppSecret";
        String serverUrl = "yourServerUrl";

        String orgId = "yourOrgId";
        String productKey = "yourProductKey";

        CreateFirmwareFileRequest request = new CreateFirmwareFileRequest();
        request.setOrgId(orgId);
        request.setProductKey(productKey);
        StringI18n stringI18n = new StringI18n("testFirmware");
        request.setName(stringI18n);

        request.setVersion("testVersion");
        // Select your firmware file
        request.setFile(new File("yourFilePath"));
        // Choose MD5 or SHA256 as signMethod, the signature of firmware file will be generated automatically
        request.setSignMethod(SignMethod.MD5);
        request.setDesc("testDesc");
        // If enableVerification is true, the firmware must be verified before you create an upgrade task
        request.setEnableVerification(false);

        CreateFirmwareFileResponse response = Poseidon
                .config(PConfig.init().appKey(appKey).appSecret(appSecret).debug())
                .url(serverUrl)
                .getResponse(request, CreateFirmwareFileResponse.class);

    }
}