com.etherios.connector.core.facilities.firmware

Interface IFirmwareUpdateImplementation

All Superinterfaces:

FirmwareConstants

All Known Implementing Classes:

GeneralFirmwareManager

public interface IFirmwareUpdateImplementation
extends FirmwareConstants

This interface defines the methods to perform firmware update operations.

The different platform customizations of the Cloud Connector should implement this interface to manage the firmware update service.

From time to time, new firmware may need to be sent to each device in certain classes. In addition, other processors may be attached to devices that need to be updated as well. The Firmware Access facility allows the operator to update the firmware for any client device defined. This facility also allows the operator to update the firmware of other processors attached to or using the client by having the client register the processor as a target. The client can define any given segment of code as a target, and therefore update sections of code indexed by the target number assigned to it.

Only one firmware target upgrade may be in progress at any given time.

• Target 0 must be the firmware that is running Cloud Connector, which may or may not be coincident with a general processing code segment. The common case is a client has one firmware image that is the full firmware image for the device, including the code that runs the microclient. This firmware must be target 0.
• Target 0xFF is a special target. When present, it indicates to the server that firmware updates happen in batches for this device. Targets are updated as usual, but the last target to be updated is 0xFF. When a download request occurs to 0xFF, this indicates that all targets have been changed and those changes can now be committed.

To help achieve a consistent firmware upgrade process, the following rules govern firmware upgrades:

• If more than one target exists on a client, the device should define regular expressions for each target. This regex indicates to the server and users of the server what filenames should be sent to a target. This does not preclude the use of explicit target numbers to identify firmware upgrades.
• When a firmware upgrade by file name occurs on the server, the following will occur (in order) to find the correct target to send the firmware upgrade to:
  1. If there is only one target (target 0x00) and no regex is specified for that target, the firmware upgrade is sent to that target; that is, in this case there is an implied regex of .* for the first target.
  2. If target 0xFF is defined, then if the file name matches commit_fw_changes the upgrade is sent to target 0xFF.
  3. The file name will be compared to each target's file name specification regex starting at target 0x00 and continuing to the end. The first match receives the upgrade. If no matches occur the firmware update fails and an error is returned.

See Also:

FirmwareTarget

Field Summary

Fields inherited from interface com.etherios.connector.core.facilities.firmware.FirmwareConstants

ABORT_DOWNLOAD_ERROR, ABORT_HARDWARE_ERROR, ABORT_INVALID_OFFSET, ABORT_SERVER_CLIENT, ABORT_UNEXPECTED_BINARY_BLOCK, ACKNOWLEDGE_LENGTH, BINARY_BLOCK_ACK_FLAG_OFFSET, BINARY_BLOCK_ACK_OFFSET_OFFSET, BINARY_BLOCK_ACK_STATUS_OFFSET, BINARY_BLOCK_DATA_OFFSET, BINARY_BLOCK_OFFSET_OFFSET, BLOCK_OFFSET_LENGTH, CHECKSUM_LENGTH, CODESIZE_LENGTH, DOWNLOAD_ABORT_STATUS_OFFSET, DOWNLOAD_COMPLETE_CHECKSUM_OFFSET, DOWNLOAD_COMPLETE_CODESIZE_OFFSET, DOWNLOAD_COMPLETE_RESPONSE_CHECKSUM_OFFSET, DOWNLOAD_COMPLETE_RESPONSE_STATUS_OFFSET, DOWNLOAD_COMPLETE_STATUS_CHECKSUM_ERROR, DOWNLOAD_COMPLETE_STATUS_ERROR, DOWNLOAD_COMPLETE_STATUS_OK, DOWNLOAD_REQUEST_CODESIZE_OFFSET, DOWNLOAD_REQUEST_ID_OFFSET, DOWNLOAD_RESPONSE_RESPONSETYPE_OFFSET, DOWNLOAD_RESPONSE_TYPE_DOWNLOAD_DENIED, DOWNLOAD_RESPONSE_TYPE_ERROR, DOWNLOAD_RESPONSE_TYPE_FILE_TOO_LARGE, DOWNLOAD_RESPONSE_TYPE_INVALID_VERSION, DOWNLOAD_RESPONSE_TYPE_NOT_ALLOWED, DOWNLOAD_RESPONSE_TYPE_NOT_AUTHENTICATED, DOWNLOAD_RESPONSE_TYPE_OK, DOWNLOAD_RESPONSE_TYPE_REJECT, DOWNLOAD_STATUS_STATUS_OFFSET, ERROR_STATUS_MALFORMED_MESSAGE, ERROR_STATUS_OFFSET, ERROR_STATUS_UNKNOWN_OPCODE, ERROR_STATUS_UNKNOWN_TARGET, INFO_RESPONSE_CODESIZE_OFFSET, INFO_RESPONSE_ID_OFFSET, OFFSET_LENGTH, OPCODE_FIRMWARE_BINARY_BLOCK, OPCODE_FIRMWARE_BINARY_BLOCK_ACK, OPCODE_FIRMWARE_DOWNLOAD_ABORT, OPCODE_FIRMWARE_DOWNLOAD_COMPLETE, OPCODE_FIRMWARE_DOWNLOAD_COMPLETE_RESPONSE, OPCODE_FIRMWARE_DOWNLOAD_REQUEST, OPCODE_FIRMWARE_DOWNLOAD_RESPONSE, OPCODE_FIRMWARE_DOWNLOAD_STATUS, OPCODE_FIRMWARE_INFO_REQUEST, OPCODE_FIRMWARE_INFO_RESPONSE, OPCODE_FIRMWARE_TARGET_LIST, OPCODE_INVALID_FIRMWARE_TARGET, OPCODE_LENGTH, OPCODE_OFFSET, OPCODE_REQUEST_TARGET_RESET, RESPONSETYPE_LENGTH, STATUS_LENGTH, TARGET_0_CODE_SIZE, TARGET_0_LABEL, TARGET_0_VALUE, TARGET_LENGTH, TARGET_OFFSET, VERSION_LENGTH, VERSION_OFFSET

Method Summary

Modifier and Type	Method and Description
int	acceptUpdateRequest(int target, java.lang.String version, int size, java.lang.String fileName, java.lang.String targetLabel, java.lang.String targetRegex) This method is called whenever a firmware download request is received for an specific target.
boolean	allowFirmwareUpdates() Retrieves whether firmware updates are allowed in this device or not.
void	downloadAbort(int target, int reason, boolean abortByServer) Notifies that the firmware update process for the given target was aborted by the server for the given reason.
int	downloadComplete(int target, int size, byte[] checksum) Handles a download complete event from the server indicating that the new firmware file has been completely transferred.
FirmwareDownloadStatus	getFirmwareDownloadStatus() Returns the firmware download status after a target update process.
java.util.List<FirmwareTarget>	getFirmwareTargets() Retrieves a list of the available firmware targets to be updated.
boolean	handleNewDataChunk(int target, int offset, byte[] dataChunk) Handles a new data chunk request for the given target with the given parameters.
void	resetTarget(int target) This method indicates a request to reset the given target was received.

Method Detail

acceptUpdateRequest

int acceptUpdateRequest(int target,
                        java.lang.String version,
                        int size,
                        java.lang.String fileName,
                        java.lang.String targetLabel,
                        java.lang.String targetRegex)

This method is called whenever a firmware download request is received for an specific target.

Parameters:

target - Target for which firmware download request is performed.

version - New firmware version.

size - Size of the new firmware.

fileName - The source file name.

targetLabel - The new label of the target (it may be an empty string). Clients may choose to ignore this field if the client decides the current label is not override-able.

targetRegex - The new regex of the target (it might be an empty string). Clients may choose to ignore this field if the client decides the current regex is not override-able.

Returns:

Download response code.

See Also:

FirmwareConstants.DOWNLOAD_RESPONSE_TYPE_OK, FirmwareConstants.DOWNLOAD_RESPONSE_TYPE_DOWNLOAD_DENIED, FirmwareConstants.DOWNLOAD_RESPONSE_TYPE_FILE_TOO_LARGE, FirmwareConstants.DOWNLOAD_RESPONSE_TYPE_INVALID_VERSION, FirmwareConstants.DOWNLOAD_RESPONSE_TYPE_NOT_AUTHENTICATED, FirmwareConstants.DOWNLOAD_RESPONSE_TYPE_NOT_ALLOWED, FirmwareConstants.DOWNLOAD_RESPONSE_TYPE_REJECT, FirmwareConstants.DOWNLOAD_RESPONSE_TYPE_ERROR

allowFirmwareUpdates

boolean allowFirmwareUpdates()

Retrieves whether firmware updates are allowed in this device or not.

Returns:

true if firmware updates are allowed, false otherwise.

downloadAbort

void downloadAbort(int target,
                   int reason,
                   boolean abortByServer)

Notifies that the firmware update process for the given target was aborted by the server for the given reason.

Parameters:

target - Target for which abort notification is sent.

reason - Reason of the firmware update abort.

abortByServer - true if the firmware download was aborted by the server, false otherwise.

See Also:

FirmwareConstants.ABORT_SERVER_CLIENT, FirmwareConstants.ABORT_DOWNLOAD_ERROR, FirmwareConstants.ABORT_INVALID_OFFSET, FirmwareConstants.ABORT_UNEXPECTED_BINARY_BLOCK, FirmwareConstants.ABORT_HARDWARE_ERROR

downloadComplete

int downloadComplete(int target,
                     int size,
                     byte[] checksum)

Handles a download complete event from the server indicating that the new firmware file has been completely transferred.

Parameters:

target - Target for which this event is sent.

size - Code size as sent in the acceptUpdateRequest(int, java.lang.String, int, java.lang.String, java.lang.String, java.lang.String) or smaller if the checksum is computed over a smaller portion of code.

checksum - CRC-32 checksum value computed from offset 0 to size (calculated by the server), 0 if no checksum is required.

Returns:

Download complete status.

See Also:

FirmwareConstants.DOWNLOAD_COMPLETE_STATUS_OK, FirmwareConstants.DOWNLOAD_COMPLETE_STATUS_CHECKSUM_ERROR, FirmwareConstants.DOWNLOAD_COMPLETE_STATUS_ERROR

getFirmwareDownloadStatus

FirmwareDownloadStatus getFirmwareDownloadStatus()

Returns the firmware download status after a target update process.

Returns:

the firmware download status.

getFirmwareTargets

java.util.List<FirmwareTarget> getFirmwareTargets()

Retrieves a list of the available firmware targets to be updated.

New firmware targets may start at index 0x00. Targets with index greater than 0xFF are ignored.

If target 0x00 is not provided or is invalid, a non-update-able target 0x00 will be created using the version returned by IConnectorPreferences.getFirmwareVersion()

Returns:

List of available firmware targets to be updated.

See Also:

FirmwareTarget

handleNewDataChunk

boolean handleNewDataChunk(int target,
                           int offset,
                           byte[] dataChunk)

Handles a new data chunk request for the given target with the given parameters.

Parameters:

target - Firmware target for which this new data chunk is sent.

offset - Offset of the new data chunk.

dataChunk - Data of the chunk.

Returns:

true if new data chunk was successfully handled, false otherwise.

resetTarget

void resetTarget(int target)

This method indicates a request to reset the given target was received.

This message is sent from the server after a successful download of the firmware. Since not all updates may require a device reset, this implementation is optional and should be used when needed.

Parameters:

target - Target number to reset.