EIR-OPS-017: Rewrite Payload Firmware


Objective

To write firmware to the GMOD/EMOD MSP.


Introduction

Using this procedure, the Operator will write a new firmware image to the GMOD/EMOD MSP.

Tip

This procedure is written using GMOD as the example. For all steps where GMOD is mentioned, identical steps can be carried out for the EMOD MSP (e.g. for the SCDB Action/Param path payload.GMOD.FirmwareVersion, simply use payload.EMOD.FirmwareVersion to access the EMOD MSP firmware version.


Procedure

This procedure has the following subsections:

A. Pre-pass Preparations
B. Rewrite Preparations
C. Reprogramming the MSP
D. Image Verification

Note

A communication window is required for Sections B - D of this procedure.


A. Pre-pass Preparations

A.1.

  • Prior to the first pass in which Section B is followed, the Operators must ensure they have access to:

    • The length of the image in rows (needed for Steps B.15, B.16 and C.5), and

    • The CRC of the image (Step B.17).

    Note

    As this image is already stored in the OBC’s flash memory at this time, no image file or image uplink is required for this procedure.


A.2.

If not already known, the Operators should now consult with the Software Engineer to determine:

  • The version of the current firmware programmed onto the MSP (needed for Step B.4),

  • Whether this firmware is expected to respond to I2C commands (Step B.4),

  • The ID of the OBC flash storage channel that holds the new firmware to be programmed onto the MSP (Step B.11), and

  • The version of the new firmware to be programmed onto the MSP (Step D.1).



B. Rewrite Preparations

Important

You are about to send the first TC of this procedure - Have you completed the EIR-OPS-003: Start a Communication Pass procedure? A Communication Pass must be started prior to carrying out the operations planned for the pass. Don’t forget to open and set-up the parameters/actions that will be required before the pass starts!

B.1.

  • Get the platform.EPS.actualSwitchStates parameter, with First row = 0 and Last row = 9.

  • If reprogramming GMOD, assess the status of rows 2, 5 and 8 of this parameter (i.e. PDMs 3, 6 and 9). If reprogramming EMOD, assess row 9 (i.e. PDM 10).

  • If 1 is returned for these rows/PDMs, the MSP is on.

Warning

PDM 8 (i.e. row 7 of this parameter) is drawing parasitic power. Therefore, when you Get the platform.EPS.actualSwitchStates parameter it will always read as on/1 even when it is powered off.

TC Details

MCS Operation

Get

Action/Param Name

platform.EPS.actualSwitchStates

Data Expected with TC

Yes

Data Size

2 bytes, 2 bytes

Data Info

First Row , Last Row

Allowed Value(s)

0-9, 0-9

Expected Value(s)

0, 9

TM Details

Data Expected from TC

actualSwitchStates ( + ACK )

Data Size

List[0:9] of Booleans

Data Info

SwitchState = 0 (Off), SwitchState = 1 (On)

Allowed Value(s)

0 or 1 for each switch

B.2.

  • If the above step shows that the MSP is on, proceed to Step B.4.

  • Else, if one or more of the MSP’s PDMs are powered off, Invoke the platform.EPS.TurnOnGMOD action. If reprogramming EMOD, instead use the platform.EPS.TurnOnEMOD action.

TC Details

MCS Operation

Invoke

Action/Param Name

platform.EPS.TurnOnGMOD

Data Expected with TC

No

TM Details

Data Expected from TC

No ( + ACK )

B.3.

  • To confirm that the MSP is now powered on, Get the platform.EPS.actualSwitchStates parameter, with First row = 0 and Last row = 9.

  • If reprogramming GMOD, ensure that rows 2, 5 and 8 of this parameter (i.e. PDMs 3, 6 and 9) now equal 1. If reprogramming EMOD, instead confirm row 9 (i.e. PDM 10) equals 1.

Warning

PDM 8 (i.e. row 7 of this parameter) is drawing parasitic power. Therefore, when you Get the platform.EPS.actualSwitchStates parameter it will always read as on/1 even when it is powered off.

TC Details

MCS Operation

Get

Action/Param Name

platform.EPS.actualSwitchStates

Data Expected with TC

Yes

Data Size

2 bytes, 2 bytes

Data Info

First Row , Last Row

Allowed Value(s)

0-9, 0-9

Expected Value(s)

0, 9

TM Details

Data Expected from TC

actualSwitchStates ( + ACK )

Data Size

List[0:9] of Booleans

Data Info

SwitchState = 0 (Off), SwitchState = 1 (On)

Allowed Value(s)

0 or 1 for each switch

Expected Value(s)

GMOD on: XX1XX1XX1X, EMOD on: XXXXXXXX1

B.4.

  • If it was determined in Section A that the firmware currently running on the MSP is non-responsive, skip ahead to Step B.8.

  • Else, Get the payload.GMOD.FirmwareVersion parameter.

  • Ensure the firmware version returned matches what was expected from Section A.

TC Details

MCS Operation

Get

Action/Param Name

payload.GMOD.FirmwareVersion

Data Expected with TC

No

TM Details

Data Expected from TC

FirmwareVersion ( + ACK )

Data Size

2 bytes (3 bytes for EMOD.FirmwareVersion)

Data Info

The version of the firmware currently on the MSP

Allowed Value(s)

0000 - FFFF (000000 - FFFFFF for EMOD.FirmwareVersion)

Expected Value(s)

Firmware version from Section A

B.5.

  • Get the payload.GMOD.GMODMode parameter to assess which mode the firmware currently running on the MSP is operating in.

Warning

The ADM firmware does not have modes. Therefore, if you are intending to overwrite ADM firmware on the EMOD MSP with EMOD experiment firmware skip ahead to Step B.8.

TC Details

MCS Operation

Get

Action/Param Name

payload.GMOD.GMODMode

Data Expected with TC

No

TM Details

Data Expected from TC

GMODMode ( + ACK )

Data Size

1 byte

Data Info

Payload operational mode

Allowed Value(s)

See table below

Where…

Firmware

Mode

Mode

GMOD

1

Idle

GMOD

2

Experiment

GMOD

3

CPLD

GMOD

4

Safe

EMOD

0

Idle

EMOD

1

Experiment

B.6.

  • If the payload.GMOD.GMODMode parameter indicates that Idle Mode is on-going, skip ahead to Step B.8.

  • Else, now Set the GMODMode parameter to Idle Mode (i.e. ‘1’ for GMOD. ‘0’ for EMOD)

TC Details

MCS Operation

Set

Action/Param Name

payload.GMOD.GMODMode

Data Expected with TC

Yes

Data Size

1 byte

Data Info

The mode to set EMOD to

Allowed Value(s)

0-1

Expected Value(s)

1 (0 for EMOD.EMODMode)

TM Details

Data Expected from TC

No ( + ACK )

B.7.

  • Confirm the Set in the previous step with a Get (i.e. confirm the value was set successfully).


B.8.

  • Get the platform.obc.GMODSerial.baudRateParam parameter.

TC Details

MCS Operation

Get

Action/Param Name

platform.obc.GMODSerial.baudRateParam

Data Expected with TC

No

TM Details

Data Expected from TC

baudRateParam ( + ACK )

Data Size

4 bytes

Data Info

The baud rate used for GMOD serial communications

Allowed Value(s)

00000000 - FFFFFFFF (hex)

B.9.

Note

When the firmware on the MSP is operating in an experiment mode, the serial port is used for science data transfer and does this at a high baud rate (i.e. 128000 baud for GMOD and 125000 baud for EMOD). However, a lower baud rate of 9600 Baud is required for reprogramming the MSP.

  • Set the platform.obc.GMODSerial.baudRateParam parameter to 9600 (decimal).

Warning

The Operator should be aware of the fact that multiple different SCDB paths are used for this procedure (i.e. payload.GMOD, platform.obc.GMODSerial and payload.FirmwareImageAccess). However, this is not a major concern as it will become obvious if an SCDB is mistaken as the parameter/action will only exist in the correct SCDB path.

TC Details

MCS Operation

Set

Action/Param Name

platform.obc.GMODSerial.baudRateParam

Data Expected with TC

Yes

Data Size

4 bytes

Data Info

The desired baud rate for GMOD serial communications

Allowed Value(s)

00000000 - FFFFFFFF (hex)

Expected Value(s)

9600 (dec) / 0x2580 (hex)

TM Details

Data Expected from TC

No ( + ACK )

B.10.

  • Confirm the Set in the previous step with a Get (i.e. confirm the value was set successfully).


B.11.

  • To programme an image from the OBC onto the MSP, the desired image must first be loaded from an OBC flash storage channel to a buffer. To start this process, first Set the payload.FirmwareImageAccess.ImageStorageChID parameter to match the storage channel ID identified in Section A.

TC Details

MCS Operation

Set

Action/Param Name

payload.FirmwareImageAccess.ImageStorageChID

Data Expected with TC

Yes

Data Size

2 bytes

Data Info

ID of the storage channel from where the firmware is to be loaded

Allowed Value(s)

0000 - FFFF (hex)

Expected Value(s)

Flash channel ID from Section A

TM Details

Data Expected from TC

No ( + ACK )

B.12.

  • Confirm the Set in the previous step with a Get (i.e. confirm the value was set successfully).


B.13.

  • Next Invoke the payload.FirmwareImageAccess.ClearImageBuffer action to clear any previous data being held in the buffer.

TC Details

MCS Operation

Invoke

Action/Param Name

payload.FirmwareImageAccess.ClearImageBuffer

Data Expected with TC

No

TM Details

Data Expected from TC

No ( + ACK )

B.14.

  • To verify that the buffer is now cleared/empty, Query the payload.FirmwareImageAccess.ImageBuffer parameter.

  • Ensure that 0 (rows) is returned.

TC Details

MCS Operation

Query

Action/Param Name

payload.FirmwareImageAccess.ImageBuffer

Data Expected with TC

No

TM Details

Data Expected from TC

Rows ( + ACK )

Data Size

2 bytes

Data Info

The number of rows of data in the buffer

Allowed Value(s)

0000 - FFFF (Hex)

Expected Value

0

B.15.

Warning

MCS does not allow the Operator to provide a decimal action argument for the action in this step. Operators will need to input the action argument in hexadecimal format.

  • Invoke the payload.FirmwareImageAccess.LoadImageFromStorage action with the input argument, Last row = the size of the image in rows - 1 (refer to Section A for the size of the image in rows).

TC Details

MCS Operation

Invoke

Action/Param Name

payload.FirmwareImageAccess.LoadImageFromStorage

Data Expected with TC

Yes

Data Size

2 bytes

Data Info

Last row = (the size of the image in rows from Section A - 1)

TM Details

Data Expected from TC

No ( + ACK )

B.16.

  • Again Query the payload.FirmwareImageAccess.ImageBuffer parameter.

  • This time, ensure that the data returned = the size of the image in rows (refer to Section A for the size of the image in rows).

TC Details

MCS Operation

Query

Action/Param Name

payload.FirmwareImageAccess.ImageBuffer

Data Expected with TC

No

TM Details

Data Expected from TC

Rows ( + ACK )

Data Size

2 bytes

Data Info

The number of rows of data in the buffer

Allowed Value(s)

0000 - FFFF (Hex)

Expected Value

The size of the image in rows from Section A

B.17.

  • To further verify the image is now correctly loaded into the buffer, Get the payload.FirmwareImageAccess.ImageCRC parameter.

  • Ensure that the data returned is equal to the CRC from Section A.

TC Details

MCS Operation

Get

Action/Param Name

payload.FirmwareImageAccess.ImageCRC

Data Expected with TC

No

TM Details

Data Expected from TC

ImageCRC ( + ACK )

Data Size

4 bytes

Data Info

CRC for the data currently being held in the ImageBuffer

Allowed Value(s)

00000000 - FFFFFFFF (hex)

Expected Value(s)

Image CRC from Section A


C. Reprogramming the MSP

C.1.

  • Get the payload.GMOD.LineNoLastProgrammed parameter.

  • Ensure that 0 is returned.

TC Details

MCS Operation

Get

Action/Param Name

payload.GMOD.LineNoLastProgrammed

Data Expected with TC

No

TM Details

Data Expected from TC

LineNoLastProgrammed ( + ACK)

Data Size

2 bytes

Data Info

Line number last programmed from the OBC to the MSP

Allowed Value(s)

0000 - FFFF (hex)

Expected Value(s)

0

C.2.

  • Invoke the payload.GMOD.FirmwareReprogramme action to first erase the firmware currently on the MSP.

TC Details

MCS Operation

Invoke

Action/Param Name

payload.GMOD.FirmwareReprogramme

Data Expected with TC

No

TM Details

Data Expected from TC

No ( + ACK )

C.3.

  • Wait ~10 seconds to allow the firmware on the MSP to be erased.


C.4.

  • Invoke the payload.GMOD.FirmwareReprogramme action again to now programme the data in the payload.FirmwareImageAccess.ImageBuffer to the MSP.

TC Details

MCS Operation

Invoke

Action/Param Name

payload.GMOD.FirmwareReprogramme

Data Expected with TC

No

TM Details

Data Expected from TC

No ( + ACK )

C.5.

  • Get and continue to Get the payload.GMOD.LineNoLastProgrammed parameter until the data returned = the size of the image in rows (determined in Section A).

Note

The reprogramming will take ~minutes. At the end of the reprogramming process, the MSP will automatically be reset and will be ready for Image Verification (Section D).

TC Details

MCS Operation

Get

Action/Param Name

payload.GMOD.LineNoLastProgrammed

Data Expected with TC

No

TM Details

Data Expected from TC

LineNoLastProgrammed ( + ACK )

Data Size

2 bytes

Data Info

Line number last programmed from the OBC to the MSP

Allowed Value(s)

0000 - FFFF (hex)

Expected Value(s)

Increasing until equal to the size of the image in rows from Section A


D. Image Verification

D.1.

  • Get the payload.GMOD.FirmwareVersion parameter.

  • Ensure that:

    • The firmware version has updated from Step B.4, and

    • The firmware version matches that determined in Section A.

TC Details

MCS Operation

Get

Action/Param Name

payload.GMOD.FirmwareVersion

Data Expected with TC

No

TM Details

Data Expected from TC

FirmwareVersion ( + ACK )

Data Size

2 bytes (3 bytes for EMOD.FirmwareVersion)

Data Info

The version of the firmware currently on the MSP

Allowed Value(s)

0000 - FFFF (000000 - FFFFFF for EMOD.FirmwareVersion)

Expected Value(s)

NEW firmware version from Section A


E. Post-Programming

E.1.

Note

When the firmware on the MSP is operating in an experiment mode, the serial port is used for science data transfer and does this at a high baud rate (i.e. 128000 baud for GMOD and 125000 baud for EMOD). However, a lower baud rate of 9600 Baud is required for reprogramming the MSP.

  • Set the platform.obc.GMODSerial.baudRateParam parameter to 128 KBaud (decimal). For the EMOD experiment, data transfer over serial occurs at 125 Kbaud (decimal).

TC Details

MCS Operation

Set

Action/Param Name

platform.obc.GMODSerial.baudRateParam

Action/Param ID

1222

Data Expected with TC

Yes

Data Size

4 bytes

Data Info

the desired baud rate

Allowed Value(s)

00000000 - FFFFFFFF (hex)

Expected Value(s)

128000 (dec)

TM Details

Data Expected from TC

No ( + ACK )

E.2.

  • Confirm the Set in the previous step with a Get (i.e. confirm the value was set successfully).


E.3.

  • In preparation for the next reprogramming, Set the payload.GMOD.LineNoLastProgrammed parameter to 0.

TC Details

MCS Operation

Set

Action/Param Name

payload.GMOD.LineNoLastProgrammed

Action/Param ID

1222

Data Expected with TC

Yes

Data Size

2 bytes

Data Info

Line number last programmed from the OBC to the MSP

Allowed Value(s)

0000 - FFFF (hex)

Expected Value(s)

0

TM Details

Data Expected from TC

No ( + ACK )

E.4.

  • Confirm the Set in the previous step with a Get (i.e. confirm the value was set successfully).


END OF PROCEDURE