com.etherios.connector.emulator.firmware

Class GeneralFirmwareManager

java.lang.Object

com.etherios.connector.emulator.firmware.GeneralFirmwareManager

All Implemented Interfaces:

FirmwareConstants, IFirmwareUpdateImplementation

public class GeneralFirmwareManager
extends java.lang.Object
implements IFirmwareUpdateImplementation

Firmware manager to process firmware update requests.

This class delegates the firmware update process to the applications that use Cloud Connector. The application must implement the interface IGeneralFirmwareImplementation that must be provided to the CloudConnector constructor.

This manager will notify the IGeneralFirmwareImplementation object of the complete download of the firmware file or of the reception of every chunk of the same file. This behavior is configured in the connector_config.txt file using the parameter "firmware_file_notify" that can be:

• "file_completed"
• "chunk_received"

The available targets to be updated via Device Cloud must be defined in a file called embedded in the jar file, following the format:

 
 <targets>
   <firmware_target id="0" name="My Target">
       <!-- Maximum allowed size of the firmware image -->
       <size>2097152</size>
       <!-- Current version of the firmware -->
       <version>0.0.0.1</version>
       <!-- Regular expression for the firmware image name -->
       <regex>.*.bin</regex>
       <!-- Determines if the firmware can be updated or not -->
       <can_update>true</can_update>
       <!-- Path to save the firmware image if the 'firmware_file_notify' 
       property of the connector_config.txt is 'file_completed' -->
       <path>/root1</path>
   </firmware_target>
   <firmware_target id="1" name="Another Target">
       [...]
   </firmware_target>
</targets>

See Also:

IGeneralFirmwareImplementation, IFirmwareUpdateImplementation

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DEFAULT_FIRMWARE_FILE_NOTIFY Default value for 'Firmware notification' setting: "file_completed".
static java.lang.String	FIRMWARE_FILE_NOTIFY_CHUNK 'Firmware notification' is thrown every time a chunk of the firmware file is received.
static java.lang.String	FIRMWARE_FILE_NOTIFY_FILE 'Firmware notification' is thrown when the firmware file is completely downloaded.
static java.lang.String	PARAM_FIRMWARE_FILE_NOTIFY 'Firmware notification' setting name: "firmware_file_notify".

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

Constructor Summary

Constructors

Constructor and Description
GeneralFirmwareManager(IPlatformCustomization platformCustomization) Class constructor.
GeneralFirmwareManager(IPlatformCustomization platformCustomization, IGeneralFirmwareImplementation generalFirmwareImpl) Class constructor.

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.
java.lang.String	getParameterValue(java.lang.String parameter) Retrieves the value of the given parameter name.
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.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_FIRMWARE_FILE_NOTIFY

public static final java.lang.String DEFAULT_FIRMWARE_FILE_NOTIFY

Default value for 'Firmware notification' setting: "file_completed".

See Also:

PARAM_FIRMWARE_FILE_NOTIFY, FIRMWARE_FILE_NOTIFY_FILE, FIRMWARE_FILE_NOTIFY_CHUNK, Constant Field Values

FIRMWARE_FILE_NOTIFY_CHUNK

public static final java.lang.String FIRMWARE_FILE_NOTIFY_CHUNK

'Firmware notification' is thrown every time a chunk of the firmware file is received.

The value of this constant is "chunk_received".

See Also:

PARAM_FIRMWARE_FILE_NOTIFY, FIRMWARE_FILE_NOTIFY_FILE, Constant Field Values

FIRMWARE_FILE_NOTIFY_FILE

public static final java.lang.String FIRMWARE_FILE_NOTIFY_FILE

'Firmware notification' is thrown when the firmware file is completely downloaded.

The value of this constant is "file_completed".

See Also:

PARAM_FIRMWARE_FILE_NOTIFY, FIRMWARE_FILE_NOTIFY_CHUNK, Constant Field Values

PARAM_FIRMWARE_FILE_NOTIFY

public static final java.lang.String PARAM_FIRMWARE_FILE_NOTIFY

'Firmware notification' setting name: "firmware_file_notify".

See Also:

FIRMWARE_FILE_NOTIFY_FILE, FIRMWARE_FILE_NOTIFY_CHUNK, DEFAULT_FIRMWARE_FILE_NOTIFY, getParameterValue(java.lang.String), Constant Field Values

Constructor Detail

GeneralFirmwareManager

public GeneralFirmwareManager(IPlatformCustomization platformCustomization)

Class constructor. Instances a new General Firmware Manager object.

Parameters:

platformCustomization - Platform customization.

GeneralFirmwareManager

public GeneralFirmwareManager(IPlatformCustomization platformCustomization,
                              IGeneralFirmwareImplementation generalFirmwareImpl)

Class constructor. Instances a new General Firmware Manager object with the given parameters.

Parameters:

platformCustomization - Platform customization.

generalFirmwareImpl - Final application firmware implementation.

Method Detail

acceptUpdateRequest

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

Description copied from interface: IFirmwareUpdateImplementation

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

Specified by:

acceptUpdateRequest in interface IFirmwareUpdateImplementation

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

public boolean allowFirmwareUpdates()

Description copied from interface: IFirmwareUpdateImplementation

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

Specified by:

allowFirmwareUpdates in interface IFirmwareUpdateImplementation

Returns:

true if firmware updates are allowed, false otherwise.

downloadAbort

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

Description copied from interface: IFirmwareUpdateImplementation

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

Specified by:

downloadAbort in interface IFirmwareUpdateImplementation

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

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

Description copied from interface: IFirmwareUpdateImplementation

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

Specified by:

downloadComplete in interface IFirmwareUpdateImplementation

Parameters:

target - Target for which this event is sent.

size - Code size as sent in the IFirmwareUpdateImplementation.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

public FirmwareDownloadStatus getFirmwareDownloadStatus()

Description copied from interface: IFirmwareUpdateImplementation

Returns the firmware download status after a target update process.

Specified by:

getFirmwareDownloadStatus in interface IFirmwareUpdateImplementation

Returns:

the firmware download status.

getFirmwareTargets

public java.util.List<FirmwareTarget> getFirmwareTargets()

Description copied from interface: IFirmwareUpdateImplementation

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()

Specified by:

getFirmwareTargets in interface IFirmwareUpdateImplementation

Returns:

List of available firmware targets to be updated.

See Also:

FirmwareTarget

getParameterValue

public java.lang.String getParameterValue(java.lang.String parameter)

Retrieves the value of the given parameter name.

Parameters:

parameter - the parameter name to get its value.

Returns:

a string representing the value of the given parameter name.

handleNewDataChunk

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

Description copied from interface: IFirmwareUpdateImplementation

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

Specified by:

handleNewDataChunk in interface IFirmwareUpdateImplementation

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

public void resetTarget(int target)

Description copied from interface: IFirmwareUpdateImplementation

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.

Specified by:

resetTarget in interface IFirmwareUpdateImplementation

Parameters:

target - Target number to reset.