Overview
The Programmer object provides the normal "command mode" for downloading firmware to Metis using UDP though an IP address.
The EEPROM in Hermes and Angelia consists of two 1 MB code partitions.
Normally, the Bootloader jumper is not installed, and the FPGA runs the command mode code that is in the upper 1 MB of the EEPROM. When the Bootloader jumper is installed, the FPGA runs the Bootloader code that is in the lower 1 MB of the EEPROM.
The Bootloader jumper is JP12 on Hermes, JP17 on Angelia and JP1 on the stand-alone Metis board.
The upper MB partition of the EEPROM includes commands to perform firmware update by using the usual IP connection (see MetisDiscovery). The Programmer object uses this connection.
The use of the Bootloader involves opening an enclosure to install the jumper. Because of that, it is more convenient to use the programmer API instead of the bootloader API. However, if the firmware in the upper MB is corrupted (for example, because of the loss of connection halfway through the command mode programming process), one will need to use the Bootloader mode (described in the Bootloader API section) to download firmware.
An example Xcode project that makes use of the Programmer class can be found in the form of a working Metis Programmer application.
Tasks
Creating a Programmer object
Writing to Metis Device
Checking Erase Status
Instance Methods
eraseStatus
Check the status of the Metis device after a -sendErase command. After sending the -sendErase, the -eraseStatus method should be repeatedly called until the returned value from it is no longer 0 (ERASE_WAITING). -eraseStatus returns immediately without blocking.
- (int)eraseStatus
Return Value
The returned integer is one of the following
0 (ERASE_WAITING)
waiting for erase command to complete (this can take more
than 10 seconds),
1 (ERASE_SUCCESSFUL)
erase command completed successfully,
-1 (ERASE_FAILED) 20
seconds have elapsed without a reply from the Metis
device.
initWithLocalAddress:remoteAddress:
Initializes the Programmer object. The local address are values associated with the computer, and the remoteAddress is associated with the Metis device.
- (id)initWithLocalAddress:(SocketAddresses*)localHost remoteAddress:(SocketAddresses*)remoteDevice
Parameters
localHost
a pointer to a
SocketAddresses structure for the local computer,
remoteDevice
a pointer to a
SocketAddresses structure for the Metis device.
The SocketAddressses structure (defined in Metis.h) is in the form
typedef struct {
in_addr_t
ip ;
unsigned char MAC[6] ;
int port ;
}
SocketAddresses ;unsigned char MAC[6] ;
int port ;
The localHost's port should contain the local port number that was used to issue the MetisDiscovery (and is the port that Metis replies to the Discovery command). Although the Metis device will respond to commands from any local host port number, its reply to the EEPROM erase command is returned to the port that it used to respond to the discovery packet (this is not mentioned in the HPSDR documentation).
The localHost structure can be obtained from the hostAddresses method of a Metis object (which contains the correct port number). The remoteDevice structure can be obtained from the metisAddresses method of a Metis object.
-initWithLocalAddress:remoteAddress: makes use of the IP address and Port of the localHost and it makes use of the IP address and Port (always 1024) of the remoteDevice.
Return Value
An initialized Programmer object.
sendErase
Erases the upper 1 MB of the FLASH memory. This has to be performed before writing the new firmware into the EEPROM. Erasing can take more than 10 seconds.
After sending a -sendErase message, repeatedly call -eraseStatus to inspect the reply from the Metis device until an ERASE_DONE (1) or ERASE_TIMEDOUT (-1) is received from -eraseStatus.
- (Boolean)sendErase
Return Value
True, if the erase command has been sent to the Metis device.
writeProgram:totalBlocks:
Data is sent in 256 byte blocks. totalBlocks is the total number of 256-byte blocks in the file, i.e., ( total bytes+255 )/256. If the last block does not use up all 256 bytes, the remaining bytes should be filled with 0xff.
The Programmer object reads the status back from Metis after sending each block of data, and returns true if the Metis device has successfully written the 256 bytes to EEPROM.
- (Boolean)writeProgram:(unsigned char*)dataBlock totalBlocks:(unsigned int)blocks
Parameters
dataBlock
byte data,
blocks
total number
blocks in file.
Return Value
True, if the Metis device acknowledges successful writing of the 256 byte EEPROM block.