You are here: CSP API Reference > 1 EXS & SwitchKit API Messages > TFTP Manage 0x003A
SwitchKit Name
TFTPManage
Type
EXS API and SwitchKit API message
Description
This message is used to download system software files and to query the TFTP configuration. You can send this message no matter what state the Matrix Controller card is in.
To download Excel platform software, send the Begin Download ICB as well as appropriate Data ICB subtypes to send the following information to the Excel platform:
• Local Matrix Configuration Filename
• Adjacent Matrix Configuration Filename
• Local Matrix Server IP Address
• Adjacent Matrix Server IP Address
• Load Timestamp
Send the Begin Download ICB whenever you assign a new TFTP configuration file that contains information about a new load.
To query the TFTP configuration, send one of the Action ICB query subtypes. The response to a query includes the corresponding Data ICB subtype.
The Timestamp ICB is required only if the timestamp is not in the configuration file.
Save Options, Load Version & Load Filename are Excel platform-initiated ICBs in response to the Query ICBs.
Adjacent Matrix ICBs are needed only if you have an adjacent matrix, but they can also be sent directly to the adjacent matrix, instead of through the local matrix.
Initiated by
SwitchKit Code
C Structure
typedef struct {
UBYTE ICBCount;
UBYTE ICBData[252];
} XL_TftpManage;
C Structure Response
typedef struct {
unsigned short Status;
UBYTE MoreStatus;
UBYTE ICBCount;
UBYTE ICBData[249];
} XL_TftpManageAck;
C++ Class
class XLC_TftpManage : public XLC_OutboundMessage {
public:
UBYTE getICBCount() const;
void setICBCount(UBYTE x);
const UBYTE *getICBData() const;
UBYTE *getICBData();
void setICBData(UBYTE *x);
};
C++ Class Response
class XLC_TftpManageAck : public XLC_AcknowledgeMessage {
public:
unsigned short getStatus() const;
void setStatus(unsigned short x);
UBYTE getMoreStatus() const;
void setMoreStatus(UBYTE x);
UBYTE getICBCount() const;
void setICBCount(UBYTE x);
const UBYTE *getICBData() const;
UBYTE *getICBData();
void setICBData(UBYTE *x);
};
EXS API Hex Format
|
MESSAGE (White) |
RESPONSE (Gray) |
||
|
Byte |
Field Description |
Byte |
Field Description |
|
0 |
Frame (0xFE) |
0 |
Frame (0xFE) |
|
1, 2 |
Length (0x00NN) |
1, 2 |
Length (0x00NN) |
|
3, 4 |
Message Type (0x003A) |
3, 4 |
Message Type (0x003A) |
|
5 |
Reserved (0x00) |
5 |
Reserved (0x00) |
|
6 |
Sequence Number |
6 |
Same Sequence Number |
|
7 |
Logical Node ID |
7 |
Logical Node ID |
|
8 |
Number of ICBs to follow |
||
|
9 |
ICB
0x01 Action ICBs 0x00* Begin Download 0x01 * Query Local Matrix Configuration Filename 0x02 * Query Local Matrix Server IP Address 0x03 * Query Adjacent Matrix Configuration 0x04 * Query Adjacent Matrix Server IP Address 0x05 * Query Timestamp 0x06 * Query Save Options
* These Action ICBs do not contain data. The Data Length is 0x00 which you have to indicate.
0x02 Data ICBs 0x37 Local Matrix Controller Configuration Filename 0x38 Local Matrix Server IP Address 0x39 Adjacent Matrix Controller Configuration Filename |
8, 9 |
Status MSB (0x00)
Status LSB: 0x00 No Timestamp Available A timestamp has not been supplied
0x01 Two Timestamps The TFTP Manage API message
0x02 Old Timestamp The supplied timestamp is older
0x03 Timestamp is Equal The supplied timestamp is equal to
0x04 Incorrect ICB Type The incorrect ICB Type is indicated |
|
: |
Checksum |
|
|
|
|
0x05 Incorrect ICB Subtype The incorrect ICB Subtype is indicated in the More Status field.
0x06 Incorrect ICB Length Fixed length ICB has wrong length or variable length (filename) ICB has a zero length.
|
||
|
|
0x07 Invalid Message Length Overall message length is less than minimum or aborts ICB in the middle.
0x08 TFTP of Configuration File Failed The failure reason is indicated in the More Status field.
0x09 TFTP Load Validation Failed The Failure Reason is indicated in the More Status field.
0x0A Load is From Wrong Release New load information is for a different load than the Excel platform is running.
0x0B Filename is greater than 127 characters. The length supplied length is indicated in the More Status field.
0x0C Unknown Load Number The host-supplied load number is greater than maximum known loads.
0x0D Response Would Be Too Long The message response would be greater than 256 bytes.
0x0E Configuration File Changes Save Option Without Begin Download ICB A new TFTP Configuration filename is not compatible with the current load configuration. |
||
|
10 |
More Status Failure Reasons
0x00 No Status 0x01 TFTP device detected a protocol error such as a non DATA packet being received or did not get expected 0x02 TFTP device timed out. Happens when IP Address is bad. 0x03 TFTP device is out of sync. 0x04 TFTP device has no more free socket IDs. Happens when another TFTP was in progress but was aborted. 0x05 TFTP device cannot use a channel number given to it. 0x06 TFTP device has not been initialized. 0x07 No server IP Address has been given. 0x08 No filename has been given. 0x09 No timestamp has been given. 0x0A A TFTP Configuration or BRecord File line is too long. 0x0B Too much data for internal buffer. 0x0C TFTP Configuration File line has no '='. 0x0D TFTP Configuration File line has no second '='. 0x0E TFTP Configuration File timestamp is missing a parameter. 0x0F Load filename is greater than 127 characters. 0x10 Matrix Controller Label in TFTP Configuration file not set to SAVE_LOAD_TRUE 0x11 Insufficient RAM. Not enough RAM on Matrix Controller card to save all loads configured to be saved. 0x12 BRecord File is out of sync. There is no 'B' starting the record. 0x13 BRecord receiver is out of sync. Expected a different record type. 0x14 Invalid BRecord Checksum 0x15 Invalid BRecord Count 0x16 Incorrect Number of Bytes in BRecord Load. 0x17 Invalid Load Checksum 0x18 Incorrect Load for Card 0x19 Incorrect Software Version. Load is from a different software version than that on the Matrix Controller. 0x1A Timeout waiting for response from download state machine 0x1B Denied by download state machine. Occurs if a traditional host download is in progress 0x1C Download state machine started a traditional host load 0x1D Timeout waiting for buffer. Occurs if download state machine has a problem 0x1E Stopped by host starting another TFTP 0x1F Configuration file has a new save option for an existing load 0x20 Operating system general error 0x21 Operating system IO error |
||
|
11 |
Number of ICBs to follow |
||
|
12 |
ICB Action ICBs 0x00 * Begin Download 0x01 * Query Local Matrix Controller Configuration Filename 0x02 * Query Local Matrix Controller Server IP Address 0x03 * Query Adjacent Matrix Controller Configuration Filename 0x04 * Query Adjacent Matrix Controller Server IP Address 0x05 * Query Timestamp 0x06 * Query Save Options * These Action ICBs do not contain data.
Data ICBs 0x37 Local Matrix Controller Configuration Filename 0x38 Local Matrix Server IP Address 0x39 Adjacent Matrix Controller Configuration Filename |
||
|
: |
Checksum |
||
Example Message (Socket Log Output for SwitchKit)
Query Local Matrix Filename
The trace below shows the TFTP Manage message sent from the host to the Excel platform to query the local matrix configuration filename. The bold number is the ICB Subtype, Query Local Matrix Configuration Filename (0x01).
Host to Excel platform:
[00 09] [00 3A] 00 00 FF 01 01 01 00
The trace below shows the response from the Excel platform. The bold numbers are the local matrix configuration filename, contained in a Query Local Matrix Configuration Filename action ICB (0x01).
Excel platform to Host:
[00 26] [00 3A] 00 00 FF [00 10] 01 01 01 [1B 63 3A 5C 74 66 74 70 62 6F 6F 74 5C 74 66 74 70 5F 6E 6F 5F 74 73 2E 63 66 67 00]