API¶
For all URLs/paths of the endpoints except File Upload, it is required to use HTTPS transfer.
File Upload¶
Note
This section focuses on the file upload from the CANlink® mobile 10000 device to the DataPlatform.
For uploading files to the CANlink® mobile 10000, you can use the REST API endpoint, see {{ rest_api_transfer_to_machine }}.
The CANlink® mobile 10000 API allows to upload files from the machine to the DataPlatform, thus DataPortal via the upload endpoint.
This endpoint allows the upload of any file format including special file extensions. The files will only be stored and made available for download on the DataPlatform. There will be no processing of the files except for .clf file types, these are reserved for internal use.
In the DataPortal, the files are then to be found in Settings > Communication Unit management > File Transfers, see File Transfer.
Note
Consider that you need Machine:Admin permissions to view the Transfers menu on DataPortal.
Restrictions¶
The file size is limited for the file upload to 50 MB from the CANlink® mobile 10000 device to the DataPlatform.
-
Filename (before the dot):
- Can contain letters, numbers, underscores (
_), and hyphens (-) - No spaces or special characters allowed
- Must be 1 to 256 characters long
- Can contain letters, numbers, underscores (
-
File extension (after the dot):
- Must be 1 to 10 characters long
- Can include only letters and numbers
- No special characters allowed
If the configuration is set to prevent automatic file upload to the DataPlatform, the files remain in the CANlink® mobile 10000's non-volatile memory until the automatic upload has been enabled again.
Request¶
URL/Path¶
Use the following path to upload the files from the machine:
http(s)://{{ address }}/upload
Example:
https://192.168.82.1/upload
It is highly recommended to use HTTPS whenever possible.
Note
To enable the http:// transfer, the HTTP option must be explicitly set in the configuration.
See also Security in the chapter Configuration Web User Interface.
Method¶
Use POST as the HTTP method.
Request Header¶
| Key | Value | Note |
|---|---|---|
| Authentication | Basic Auth | Basic Authentication with username and password is used as the authorization type. The username is upload and isn't changeable. There is no default password for the uploads; before using the feature, you must explicitly set a password (or alternatively, disable password protection) in the configuration web UI. The passwords are write-only and cannot be read back. See also Security. |
| Content-Type | form-data | - |
Request Body¶
| Key | Value | Note |
|---|---|---|
| file | Any binary file | Read about the Restrictions. |
Response¶
There are the following HTTP Status Codes:
| Status | Note |
|---|---|
| 200 | OK, file transfer to the DataPlatform succeeded. |
| 400 | Bad request (missing required file form field, missing form field value (file name), not a POST. |
| 401 | Authentication failure, i.e. wrong username (must be upload) or wrong password. |
| 403 | Transfer forbidden, file uploads to the unit have been disabled by the user in the device configuration. |
| 413 | Payload too large, currently the size of the upload is limited to 1 MB per file. |
| 500 | Unexpected internal error in the application, review the logs. |
Access uploaded Files on DataPlatform¶
You can obtain the uploaded files as follows:
-
In the DataPortal go to Settings > Communication Unit management > File Transfers and click Save to download the file. For more information, read File Transfer in the DataPortal User Manual.
-
For the download of the files from the DataPlatform, read Transfers in the REST API.
Firmware Update¶
The CANlink® mobile 10000 API allows to update the firmware via the firmware endpoint.
This endpoint allows the upload of a firmware update in the .swu file format.
Note
Consider that the Configuration Web User Interface also allows the upload of firmware files.
Request¶
URL/Path¶
Use the following path to upload the files from the machine:
https://{{ address }}/firmware
Example:
https://192.168.82.1/firmware
Method¶
Use POST as the HTTP method.
Request Header¶
| Key | Value | Note |
|---|---|---|
| Authentication | Basic Auth | Basic Authentication with username and password is used as the authorization type. The username is admin and isn't changeable. The default password is the Ethernet MAC address in capital letters without colons. You can change the password in the configuration web UI (note that password protection cannot be disabled). The passwords are write-only and cannot be read back. See also [Security](configuration_web_user_interface.md#security |
| Content-Type | form-data | - |
Body¶
| Key | Value | Note |
|---|---|---|
| file | .swu binary file |
- |
Response¶
There are the following HTTP Status Codes:
| Status | Note |
|---|---|
| 200 | OK, firmware image transfer succeeded |
| 400 | Bad request (missing required file form field, missing form field value (file name), not a POST. |
| 401 | Authentication failure, i.e. wrong username (must be admin) or wrong password. |
| 500 | Unexpected internal error in the application, review the logs. |
After receiving the firmware image the device will start the firmware update procedure, a response code of 200/HTTP OK only means that the image has been accepted for further processing, it does not indicate a successful update.
In the Configuration Web User Interface, the successfully updated firmware will be displayed as new entry in the Updates > Firmware menu.
Configuration Update¶
The CANlink® mobile 10000 API allows to update the configuration via the config endpoint.
This endpoint allows the upload of a previously exported configuration in the .clm file format.
Consider that the Configuration Web User Interface also allows the upload of configuration files.
Request¶
URL/Path¶
Use the following path to upload the files from the machine:
https://{{ address }}/config
Example:
https://192.168.82.1/config
Method¶
Use POST as the HTTP method.
Request Header¶
| Key | Value | Note |
|---|---|---|
| Authentication | Basic Auth | Basic Authentication with username and password is used as the authorization type The username is admin and isn't changeable. The default password is the Ethernet MAC address in capital letters without colons. You can change the password in the configuration web UI (note that password protection cannot be disabled). The passwords are write-only and cannot be read back. See also Security. |
| Content-Type | form-data | - |
Body¶
| Key | Value | Note |
|---|---|---|
| file | .clm binary file |
- |
Response¶
There are the following HTTP Status Codes:
| Status | Note |
|---|---|
| 200 | OK, file transfer transfer succeeded |
| 400 | Bad request (missing required file form field, missing form field value (file name), not a POST. |
| 401 | Authentication failure, i.e. wrong username (must be admin) or wrong password. |
| 500 | Unexpected internal error in the application, review the logs. |
After receiving a configuration file the device will try to apply provided settings. The operation is atomic, meaning that either all settings can be applied successfully or nothing will be applied at all in case one or more settings fail. A response code of 200/HTTP OK only means that the config file has been accepted for further processing, it does not indicate if settings were applied.
In the Configuration Web User Interface, the successfully updated configuration will be displayed as new entry in the Updates > Configuration menu.