Firmware for the CUBesat x-ray Explorer using Scintillators (CUBES)

• Introduction
• Getting Started
  • Code Summary
• Folder Structure
  • Regenerating the firmware folder
  • Regenerating the msp folder
• Programming
  • Programming Port
  • Board ID
  • Debug: Program to CUBES RAM
  • Production: Program to CUBES NVM

Introduction

The code on this repository runs on the Cortex-M3 core embedded on the SmartFusion2 FPGA.

Getting Started

1. Download and install SoftConsole

• NOTE: Latest version to support Cortex-M3 development is 2021.1
• Download from Microchip website

2. Clone this repository/unzip the archive downloaded via GitHub
3. Import this project from the repo/unzipped archive into SoftConsole
4. Program firmware to RAM or to NVM.

Code Summary

Most of the code is under main.c, in the while (1) loop:

• REQ_HK data is prepared once a second; the second counting is handled by Timer1_IRQHandler;
• REQ_PAYLOAD data is prepared once the DAQ has finished; note that this is a lenghty process (several hundreds of microseconds), especially if histogram binning is performed;
• Prepping data for and acting upon data from MSP commands are then handled in the next if/else if statements:
  • if (has_send) for MSP send commands (from CUBES to OBC);
  • else if (has_rcvd) for MSP receive commands (by CUBES from OBC);
  • else if (has_syscommand) for MSP system commands (for CUBES from OBC).

MSP callbacks functions and main I2C ISR are also present at the bottom of main.c.

• MSP send (CUBES to OBC)
  • msp_expsend_start is where the MSP send buffer is assigned to the data to be sent; the has_send variable is also assigned, which informs the main loop to update with new send data based on MSP command;
  • MSP frames are then sent via msp_expsend_data (msp_expsend_complete only clears the REQ_PAYLOAD buffer so it doesn't contain stale data in case of a new REQ_PAYLOAD being issued);
• MSP receive (CUBES from OBC)
  • msp_exprecv_start clears the MSP receive buffer for new data;
  • msp_exprecv_data buffers in data retrieved in MSP frames
  • msp_exprecv_complete informs the main loop the data is ready to be processed
• The whole process for sending MSP frames starts in I2C1_SlaveWriteHandler, which essentially (1) waits for an MSP frame from the OBC, msp_recv_callback; and (2) sends a reply MSP frame to the OBC, msp_send_callback.
• NOTE: To better understand the way MSP functions, right-click any of the MSP callbacks, (e.g., msp_expsend_start or msp_exprecv_data), then click Open Call Hierarchy.

Other folders under cubes-fw contain various APIs for handling devices on the CUBES board.

Folder Structure

• cubes-fw
  • firmware // Code generated from Libero
  • hk_adc // API to handle the ADS1015 ADC
  • hvps // API to handle the C11204-02 HVPS module
  • mem // API to handle CUBES memory accesses
  • msp // MSP API functions, generated using the Python script supplied with MSP
  • utils // Various utilitary APIs, e.g., to handle the on-board LED

Regenerating the firmware folder

• See firmware/README.md.

Regenerating the msp folder

• Externally from the cubes-fw repository, obtain the MSP repository from GitLab:
  • git clone https://gitlab.com/kth-mist/msp msp-repo
• Copy/move the file cubes-fw/msp/msp_configuration.h to somewhere you know; this file will need to replace whatever gets generated by the MSP conf.py script!
• Delete all contents inside the cubes-fw/msp/ folder;
• Use msp-repo/conf.py to generate a new set of MSP files;
• Copy these files from msp-repo/target/ to cubes-fw/msp/.
• Copy back the msp_configuration.h file you saved earlier over that generated by the conf.py script.

Programming

Programming Port

CUBES should be programmed using a FlashPro5 programmer from Microchip. The standard 10-pin JTAG connector supplied with the FlashPro5 should be adapted to the 1.27-mm pitch programming port on the CUBES board using a 2.54-to-1.27-mm adapter:

• https://www.mikroe.com/50-100mil-adapter-board

One such adapter can be found in AlbaNova, in the "PoGO lab" on the bottom floor of the building. The adaptor should be located in the plastic box labeled "CUBES".

Board ID

Each CUBES board has its own ID, labeled on the top side of CUBES boards, corresponding to the -Z face of the satellite. The number on this label corresponds to the second character in the BOARD_ID macro, defined via a -D compiler flag (see programming sections below):

• BOARD_ID = C<number-on-label> (C stands for CUBES, <number-on-label> corresponds to board number, 1 through 5)

• Board IDs:

  • BOARD_ID = C3 for CUBES-1 on MIST
  • BOARD_ID = C4 for CUBES-2 on MIST
  

Debug: Program to CUBES RAM

1. Open the Properties window for the cubes-fw project by either right-clicking the project in SoftConsole and pressing Properties in the pop-up menu, or selecting the project in SoftConsole and hitting Alt+Enter on your keyboard.

2. Navigate to C/C++ Build > Settings > GNU ARM Cross C Linker > General and double-click the script file:

   

3. Ensure the esram linker script is used for programming:

   

4. Still in the Properties window, C/C++ Build > Settings, navigate to GNU ARM Cross C Compiler > Preprocessor.

5. Change the BOARD_ID macro for the board you are programming as outlined in the Board ID section above (note the escape characters before each double quote):

   • BOARD_ID = \"C3\" or

   • BOARD_ID = \"C4\"

     

6. Change the MSP_EXP_ADDR macro for the board according to the i2c.h config file under the obcsw GitLab repository, nominally:

   • MSP_EXP_ADDR = 0x35 for CUBES-1
   • MSP_EXP_ADDR = 0x36 for CUBES-2

   

7. Press the Apply and Close button in the Properties dialog.

8. Connect the FlashPro5 programmer to the CUBES PCB of interest.

9. Press the Debug (bug) button on the SoftConsole interface.

10. The code should now be programmed to CUBES volatile memory; HK can be read out from CUBES and checked if it "makes sense".

Production: Program to CUBES NVM

1. Open the Properties window for the cubes-fw project by either right-clicking the project in SoftConsole and pressing Properties in the pop-up menu, or selecting the project in SoftConsole and hitting Alt+Enter on your keyboard.

2. Navigate to C/C++ Build > Settings > GNU ARM Cross C Linker > General and double-click the linker script file:

   

3. To ensure the code is programmed to non-volatile memory, change esram to envm at the very end of the text line in the dialog that appears:

   

4. Still in the Properties window, C/C++ Build > Settings, navigate to GNU ARM Cross C Compiler > Preprocessor.

5. Change the BOARD_ID macro for the board you are programming as outlined in the Board ID section above (note the escape characters before each double quote):

   

6. Change the MSP_EXP_ADDR macro for the board according to the i2c.h config file under the obcsw GitLab repository, nominally:

   • MSP_EXP_ADDR = 0x35 for CUBES-1
   • MSP_EXP_ADDR = 0x36 for CUBES-2

   

7. Click the Debug (yes -- Debug!) button in the SoftConsole main window to program the board. The Console window should display information about it programming to NVM. Programming should also take longer than in the case of RAM.

8. End the debug session from SoftConsole's Debug perspective.

9. Move the FlashPro5 programmer from the board you just programmed to the next one you want to program.

10. Repeat steps 4-7.

    • NOTE: Remember that the BOARD_ID and MSP_EXP_ADDR macros need to be different.

11. Reset the CUBES stackup by power-cycling the 5V_CUBES power rail.

12. Perform a REQ_HK MSP command from each of the two CUBES boards and ensure the readouts "make sense".

IMPORTANT:

• Revert the .cproject file back to its original contents, to ensure you are not unnecessarily programming to NVM next time:

  git restore .cproject