File Operations Overview
HSES is a useful protocol for developing programs (in languages other than C++) that interface with Yaskawa Motoman robots. If you are developing a program in C++, YMConnect is a better choice that implements functionality from HSE without the need to program a network stack.
In order to use HSES, you will need to have a basic understanding of networking and socket programming.
HSES has the capability to load files onto the controller, save files from the controller, list files on the controller, and delete files from the controller. This article will cover the basic packet structure for file operations.
File Operations Packet Header Structure
+----------------------+---------+-------------------------------------------------------------------------------+------------------------------------------+
| Field | Size | Description | Hardcoded value (if applicable) |
+----------------------+---------+-------------------------------------------------------------------------------+------------------------------------------+
| Identifier | 4 Bytes | The identifier is always ASCII "YERC." | 0x59 0x45 0x52 0x43 |
| Header Length | 2 Bytes | The length of the header. | 0x0020 |
| Data Length | 2 Bytes | The length of the data payload. | N/A |
| Reserve 1 | 1 Byte | Fixed to “3.” | 0x03 |
| Processing division | 1 Byte | Specifies that this packet is a file command. | 0x02 |
| ACK | 1 Byte | Specifies if this is an initial request or a reply.* | 0x0 for initial request, 0x01 for reply |
| Request ID | 1 Byte | Sequential identifying id of the packet.** | N/A |
| Block Number | 4 Bytes | Specifies the number of the packet in a block of communication.*** | N/A |
| Reserve 2 | 8 Bytes | Fixed to “99999999.” | 0x39 0x39 0x39 0x39 0x39 0x39 0x39 0x39 |
+----------------------+---------+-------------------------------------------------------------------------------+------------------------------------------+
* The ACK field is used to determine if the packet is a request or a response. If the ACK field is 0x00, the packet is a request. If the ACK field is 0x01, the packet is either a response to a request or a continuation of a previous command. Demonstrated in example packet flow.
** Increment this ID every time the client side outputs a new command. In reply to this, server side answers the received value. Max value is 0xFF. If the value exceeds 0xFF, reset the value to 0x00.
*** The Block Number increments for a reply to a packet that is still applicable to a previous command. For Example, the following would be an example of how the block number increments in a file load command. Demonstrated in example packet flow. Note the request ID and the Block Id differences.
File Operations Packet Request Subheader
+-----------+---------+-----------------------------------+---------------------------------------+
| Field | Size | Description | Hardcoded value (if applicable) |
+-----------+---------+-----------------------------------+---------------------------------------+
| Command | 2 Bytes | Set to 0x00 for file operations. | 0x00 |
| Instance | 2 Bytes | Set to 0x00 for file operations. | 0x00 |
| Attribute | 1 Byte | Set to 0x00 for file operations. | 0x00 |
| Service | 1 Byte | File operation to execute. | See File Operation Service Code table |
| Padding | 1 Byte | Set to 0x00. | 0x00 |
+-----------+---------+-----------------------------------+---------------------------------------+
File Operations Packet Response Subheader
+--------------------+------------+---------------------------------------------------------------------------------------------------------+---------------------------------+--+
| Field | Size | Description | Hardcoded value (if applicable) | |
+--------------------+------------+---------------------------------------------------------------------------------------------------------+---------------------------------+--+
| Service | 1 Byte | Add 0x80 to service (request). | N/A | |
| Status | 1 Byte | 0x00: normal reply, 0x1f: abnormal reply with added status else abnormal reply with no added status. | N/A | |
| Added Status Size | 1 Byte | Size of added status in bytes. | N/A | |
| Padding | 1 Byte | Fixed to “0.” | 0x00 | |
| Added Status | 2 Bytes | Error code specified by added status size. | N/A | |
| Padding | 2 Bytes | Fixed to “0.” | 0x00 0x00 | |
+--------------------+------------+---------------------------------------------------------------------------------------------------------+---------------------------------+--+
File Operation Service Code Table
+--------------+----------------------------+
| Service Code | Description |
+--------------+----------------------------+
| 0x09 | Delete file. |
| 0x15 | Load file to controller. |
| 0x16 | Save file from controller. |
| 0x32 | List files on controller. |
+--------------+----------------------------+
Delete File
When deleting a file, set the data length to the size of the file name in bytes. for example, if the file name is "TESTJOB.JBI", the data length field would be set to 0x000B. The data payload would be the file name in ASCII. The file name must be all caps with the file extension included.
Here is an example of a delete file request packet:
+---------------------+------------------------------------------------------------------------+
| Field | value |
+---------------------+------------------------------------------------------------------------+
| Identifier | 0x59 0x45 0x52 0x43 |
| Header Length | 0x0020 |
| Data Length | 0x000B |
| Reserve 1 | 0x03 |
| Processing division | 0x02 |
| ACK | 0x00 |
| Request ID | 0x00 |
| Block Number | 0x00000000 |
| Reserve 2 | 0x39 0x39 0x39 0x39 0x39 0x39 0x39 0x39 |
| Command | 0x00 0x00 |
| Instance | 0x00 0x00 |
| Attribute | 0x00 |
| Service | 0x09 |
| Padding | 0x00 |
| Data Payload | 0x54 0x45 0x53 0x54 0x4A 0x4F 0x42 0x2E 0x4A 0x42 0x49 ("TESTJOB.JBI") |
+---------------------+------------------------------------------------------------------------+
Upon receiving a delete file request, the controller will respond with a delete file response packet.
Example delete file response packet:
+---------------------+-----------------------------------------+
| Field | Value |
+---------------------+-----------------------------------------+
| Identifier | 0x59 0x45 0x52 0x43 |
| Header Length | 0x0020 |
| Data Length | 0x0000 |
| Reserve 1 | 0x03 |
| Processing division | 0x02 |
| ACK | 0x01 |
| Request ID | 0x00 |
| Block Number | 0x80000000 |
| Reserve 2 | 0x39 0x39 0x39 0x39 0x39 0x39 0x39 0x39 |
| Service | 0x89 |
| Status | 0x00 |
| Added Status Size | 0x00 |
| Padding | 0x00 |
| Added Status | 0x00 0x00 |
| Padding | 0x00 0x00 |
+---------------------+-----------------------------------------+
Load File
When loading a file, set the data length to the size of the file name in bytes. for example, if the file name is "TESTJOB.JBI", the data length field would be set to 0x000B. The data payload would be the file name in ASCII. The file name must be all caps with the file extension included. This is for the first packet of a file load. The subsequent packets will contain the file data. The maximum size of the data payload is 479 bytes(0x1DF).
Here is an example of a load file request packet:
+---------------------+------------------------------------------------------------------------+
| Field | value |
+---------------------+------------------------------------------------------------------------+
| Identifier | 0x59 0x45 0x52 0x43 |
| Header Length | 0x0020 |
| Data Length | 0x000B |
| Reserve 1 | 0x03 |
| Processing division | 0x02 |
| ACK | 0x00 |
| Request ID | 0x00 |
| Block Number | 0x00000000 |
| Reserve 2 | 0x39 0x39 0x39 0x39 0x39 0x39 0x39 0x39 |
| Command | 0x00 0x00 |
| Instance | 0x00 0x00 |
| Attribute | 0x00 |
| Service | 0x15 |
| Padding | 0x00 |
| Data Payload | 0x54 0x45 0x53 0x54 0x4A 0x4F 0x42 0x2E 0x4A 0x42 0x49 ("TESTJOB.JBI") |
+---------------------+------------------------------------------------------------------------+
Upon receiving a load file request, the controller will respond with a load file response packet.
Example load file response packet:
+---------------------+-----------------------------------------+
| Field | Value |
+---------------------+-----------------------------------------+
| Identifier | 0x59 0x45 0x52 0x43 |
| Header Length | 0x0020 |
| Data Length | 0x0000 |
| Reserve 1 | 0x03 |
| Processing division | 0x02 |
| ACK | 0x01 |
| Request ID | 0x00 |
| Block Number | 0x80000000 |
| Reserve 2 | 0x39 0x39 0x39 0x39 0x39 0x39 0x39 0x39 |
| Service | 0x95 |
| Status | 0x00 |
| Added Status Size | 0x00 |
| Padding | 0x00 |
| Added Status | 0x00 0x00 |
| Padding | 0x00 0x00 |
+---------------------+-----------------------------------------+
Example Load file data packet flow:
Send: Load file "TESTJOB.JBI" (Ack: 0x00, Request ID: 0x00, Block number: 0x00000000)
Response: Received request to load file "TESTJOB.JB" (Ack: 0x01, Request ID: 0x00, Block number: 0x00000000)
Send: Send first block of file "TESTJOB.JBI" (Ack: 0x01, Request ID: 0x00, Block number: 0x00000001)
Response: Received first block of file "TESTJOB.JBI" (Ack: 0x01, Request ID: 0x00, Block number: 0x00000001)
Send: Send second block of file "TESTJOB.JBI" (Ack: 0x01, Request ID: 0x00, Block number: 0x00000002)
Response: Received second block of file "TESTJOB.JBI" (Ack: 0x01, Request ID: 0x00, Block number: 0x00000002)
Send: Send last block of file "TESTJOB.JBI" (Ack: 0x01, Request ID: 0x00, Block number: 0x80000003)
Response: Received last block of file "TESTJOB.JBI" (Ack: 0x01, Request ID: 0x00, Block number: 0x80000003)
Save File
When saving a file, set the data length to the size of the file name in bytes. for example, if the file name is "TESTJOB.JBI", the data length field would be set to 0x000B. The data payload would be the file name in ASCII. The file name must be all caps with the file extension included. This is for the first packet of a file save. The subsequent packets will contain the file data. The maximum size of the data payload is 479 bytes(0x1DF).
Here is an example of a save file request packet:
+---------------------+------------------------------------------------------------------------+
| Field | Value |
+---------------------+------------------------------------------------------------------------+
| Identifier | 0x59 0x45 0x52 0x43 |
| Header Length | 0x0020 |
| Data Length | 0x000B |
| Reserve 1 | 0x03 |
| Processing division | 0x02 |
| ACK | 0x00 |
| Request ID | 0x00 |
| Block Number | 0x00000000 |
| Reserve 2 | 0x39 0x39 0x39 0x39 0x39 0x39 0x39 0x39 |
| Command | 0x00 0x00 |
| Instance | 0x00 0x00 |
| Attribute | 0x00 |
| Service | 0x16 |
| Padding | 0x00 |
| Data Payload | 0x54 0x45 0x53 0x54 0x4A 0x4F 0x42 0x2E 0x4A 0x42 0x49 ("TESTJOB.JBI") |
+---------------------+------------------------------------------------------------------------+
Upon receiving a save file request, the controller will respond with a save file response packet.
Example save file response packet:
+---------------------+-----------------------------------------+
| Field | value |
+---------------------+-----------------------------------------+
| Identifier | 0x59 0x45 0x52 0x43 |
| Header Length | 0x0020 |
| Data Length | Size of first block. |
| Reserve 1 | 0x03 |
| Processing division | 0x02 |
| ACK | 0x01 |
| Request ID | 0x00 |
| Block Number | 0x00000001 |
| Reserve 2 | 0x39 0x39 0x39 0x39 0x39 0x39 0x39 0x39 |
| Service | 0x96 |
| Status | 0x00 |
| Added Status Size | 0x00 |
| Padding | 0x00 |
| Added Status | 0x00 0x00 |
| Padding | 0x00 0x00 |
| Data Payload | First N bytes of file. |
+---------------------+-----------------------------------------+
Example Save file data packet flow:
Send: Save file "TESTJOB.JBI" (Ack: 0x00, Request ID: 0x00, Block number: 0x00000000)
Response: Received request to save file "TESTJOB.JBI." Send first block(Ack: 0x01, Request ID: 0x00, Block number: 0x00000001)
Send: Received first block of file "TESTJOB.JBI" (Ack: 0x01, Request ID: 0x00, Block number: 0x00000001, Data Length: 0x00)
Response: Send second block of file "TESTJOB.JBI" (Ack: 0x01, Request ID: 0x00, Block number: 0x00000002)
Send: Received second block of file "TESTJOB.JBI" (Ack: 0x01, Request ID: 0x00, Block number: 0x00000002, Data Length: 0x00)
Response: Send last block of file "TESTJOB.JBI" (Ack: 0x01, Request ID: 0x00, Block number: 0x80000003)
Send: Received last block of file "TESTJOB.JBI" (Ack: 0x01, Request ID: 0x00, Block number: 0x80000003, Data Length: 0x00)
List Files
When listing files, set the data length to 0x0005. The data payload would be "*.EXT" where EXT is the file extension. The file extension must be all caps.
File extension table:
+----------------+-------------+
| File Extension | Description |
+----------------+-------------+
| *.JBI | Job file |
| *.DAT | DAT file |
| *.CND | CND file |
| *.PRM | PRM file |
| *.SYS | SYS file |
| *.LST | LST file |
+----------------+-------------+
Here is an example of a list files request packet:
+---------------------+-----------------------------------------+
| Field | Value |
+---------------------+-----------------------------------------+
| Identifier | 0x59 0x45 0x52 0x43 |
| Header Length | 0x0020 |
| Data Length | 0x0005 |
| Reserve 1 | 0x03 |
| Processing division | 0x02 |
| ACK | 0x00 |
| Request ID | 0x00 |
| Block Number | 0x00000000 |
| Reserve 2 | 0x39 0x39 0x39 0x39 0x39 0x39 0x39 0x39 |
| Command | 0x00 0x00 |
| Instance | 0x00 0x00 |
| Attribute | 0x00 |
| Service | 0x32 |
| Padding | 0x00 |
| Data Payload | 0x2A 0x2E 0x4A 0x42 0x49 ("*.JBI") |
+---------------------+-----------------------------------------+
Upon receiving a list files request, the controller will respond with a list files response packet.
Example list files response packet:
+---------------------+-----------------------------------------+
| Field | Value |
+---------------------+-----------------------------------------+
| Identifier | 0x59 0x45 0x52 0x43 |
| Header Length | 0x0020 |
| Data Length | Size of file list. |
| Reserve 1 | 0x03 |
| Processing division | 0x02 |
| ACK | 0x01 |
| Request ID | 0x00 |
| Block Number | 0x80000000 |
| Reserve 2 | 0x39 0x39 0x39 0x39 0x39 0x39 0x39 0x39 |
| Service | 0xB2 |
| Status | 0x00 |
| Added Status Size | 0x00 |
| Padding | 0x00 |
| Added Status | 0x00 0x00 |
| Padding | 0x00 0x00 |
| Data Payload | List of files. |
+---------------------+-----------------------------------------+
Comments
0 comments
Please sign in to leave a comment.