5. HTTP Communication
5.1. Basics
Section titled “5.1. Basics”The service runs on the standard HTTP port (port 80). Unless otherwise specified, the base address for requests is /api/cnc. A standard request URL has the following format:
http://{Gateway IP}/api/cnc/{Interface Name}?MachineID={Target Machine machineID}For example, if the gateway’s IP address is 192.168.100.1, and you want to obtain the running status of the main channel of a machine tool connected to this gateway with IP 192.168.1.10 and MachineID 1010 (for an explanation of machineID, see 4.1.1. machineID Machine Identifier), you should use the /readCNCStatus interface, and the corresponding request URL is:
http://192.168.100.1/api/cnc/readCNCStatus?MachineID=1010Request bodies use Content-Type application/json by default. File and stream interfaces (such as sendFileStream, upload-license and upload-alarm-mapping-file) use application/octet-stream or text/plain to upload binary/text content. Only POST/PUT requests read the request body.
Except for a few file-related interfaces, most interfaces return HTTP data of type application/json.
All data must be encoded in UTF-8.
In the descriptions below, some interfaces require additional input parameters in the request URL.
5.1.1. Forwarding Requests Through the Cloud Platform or Hub
Section titled “5.1.1. Forwarding Requests Through the Cloud Platform or Hub”HTTP requests can also be forwarded to the target gateway through a cloud platform or Hub server. First complete the gateway’s 3.6.1. Cloud Settings or 3.6.7. Hub Settings, click Save, go back to Home and click Restart Service, then confirm that the gateway is connected to the corresponding server.
- Replace the gateway address in the request URL with the corresponding cloud platform or Hub server address. Use the protocol (HTTP or HTTPS) and port configured for that server. Keep the interface path, parameters, request method and request body unchanged.
- Add an
AccessTokenrequest header. Set its value to the gateway token entered in Token in the corresponding Cloud Settings or Hub Settings. The server uses this token to forward the request to that gateway.
For example, to obtain the running status of a machine’s main channel through the cloud platform or Hub, use the following request URL:
http://{Cloud platform or Hub server address}/api/cnc/readCNCStatus?machineID=1010Add the following request header:
AccessToken: {Gateway token}Replace the server address, gateway token and machineID in the example with their actual values. Enter the gateway token directly as the AccessToken value, without a Bearer prefix.
5.2. Error Handling
Section titled “5.2. Error Handling”Whenever an error occurs in a request, an error object is returned as follows:
{ "errorCode": 1, "errorMsg": "Unexpected Error."}| Response Parameter | Type | Description |
|---|---|---|
| errorCode | Int32 | (Required) Error code, 0 indicates success. |
| errorMsg | String | (Required) Error message |
| statusMsg | String | (Optional) Error detail providing additional context; not returned when empty |
When the operation succeeds, the corresponding data is returned, and the HTTP status code is 200 in this case.
When an error occurs, an error code is returned, and the HTTP status code is 400 (bad or unsupported request), 401 (unauthorized), 404 (interface or path not found), 409 (conflict), 502 (machine unreachable) or 503 (any other error, the default). Common error codes are as follows:
Common Error Codes
Section titled “Common Error Codes”| Error Code | Message | Description |
|---|---|---|
| 0 | Success | Operation executed successfully |
| 3 | Machine off or offline | Unable to communicate with the machine tool; the machine tool is powered off or there is a network hardware fault (machine tool network port, switch, network cable, etc.) |
| 7 | No permission | The interface is protected or out of authorization scope, or the authentication information is invalid. |
| 101 | Function not supported by the current system | The machine tool control system does not support this interface |
| 102 | Machine network fault, unable to obtain data | Able to communicate with the machine tool, but unable to obtain data; there is an issue with the machine tool’s network settings |
| 125 | Invalid file path | The input file path is invalid |
| 142 | File already exists | A file with the same name already exists in the target directory |
| 143 | File is in use | The file to be operated on is currently in use |
| 144 | File is write-protected | The file to be operated on is write-protected |
| 158 | File does not exist | The target file does not exist in the target directory |
| 10003 | machineID does not exist | The machineID is incorrect, the corresponding machine is not activated, or the gateway service was not restarted after editing the machine’s IP or activation status |
| 10006 | Interface not authorized | To use an unauthorized interface, please contact BIVROST |
| 10017 | Invalid request | A request parameter is missing, has the wrong type, or cannot be parsed |
| 10051 | WiFi not available | The gateway has no usable wireless adapter or the WLAN service is unavailable; statusMsg carries the cause |

