cFS Tutorial Part 3: Putting messages onto the (Local) Software Bus

by David Ferreira, Fourier Automation

Preface & Links

This is part 3 in a series of tutorials from Fourier Automation on using NASA's core Flight System (cFS), an embedded software framework used in everything from cubesats to NASA's flagship spacecraft.

Video accompanying this post: cFS Tutorial 3: All Aboard the cFS Software Bus

The entire tutorial series: Fourier Automations cFS Tutorial Playlist

NASA training material: Core Flight System (cFS) Training

Putting Messages onto the cFS Software Bus

A key component of NASA's cFS Framework is the (local) Software Bus or SB. This structure facilitates the publication of messages by a sending application to one or more subscriber applications.

On a higher level, cFS also has a Software Bus Network (SBN) which connects various systems running cFS locally. But in this video, we will limit ourselves to learning how place messages onto the local software bus (SB) from our sample application.

For a more in-depth understanding understanding of a generic message bus architecture pattern, please take a look at this article.

Additionally, for a more in-depth understanding of the cFS Software Bus Network (SBN), we would recommend this video presentation by Christopher Knight from NASA's Ames Research Center.

Prerequisite(s)

To use this tutorial, it is recommended that you have:

• cFS setup to build & run on your Linux machine or Linux VM (or other Posix-compatible computer).
  
  If you are not at this waypoint yet and you're not sure how to accomplish this, please take a quick look at our first tutorial in this series (link below):
  
  cFS Tutorial 1: Build & Run NASA's core Flight System (cFS)
  
  
• (Optional) A cursory understanding of a software message bus architecture pattern, which includes an understanding of a queue (a fundamental data structure).

Steps

There are 3 common methods for placing messages on the software bus (SB):

• CFE_SB_TransmitBuffer()
• CFE_SB_TransmitMsg(), and
• CFE_EVS_SendEvent(). In this case the message placed on the SB is something of an incidental side-effect of creating an Event in the Event System (EVS).

In order to keep things simple, we are going to consider 1 set of minimum initialization steps for all three methods, since we would most likely use CFE_EVS_SendEvent() to publish the results of our SB initialization steps (success or failure).

In order to place a message on the SB, we need to execute 4 initialization steps:

1. Register your app with the Event Service (EVS) by calling: CFE_EVS_Register();
   

   /*
   ** Register the events
   */
   status = CFE_EVS_Register(NULL, 0, CFE_EVS_EventFilter_BINARY);
   if (status != CFE_SUCCESS)
   {
   	 CFE_ES_WriteToSysLog("Some error message, RC = 0x%08lX\n", (unsigned long)status);
   }
   else{...}
   

2. Initialize Messaging Service (MSG) by calling: CFE_MSG_Init();
   

   /*
    ** Initialize housekeeping packet (clear user data area).
    */
   CFE_MSG_Init(CFE_MSG_PTR(SAMPLE_APP_Data.HkTlm.TelemetryHeader),
   			 CFE_SB_ValueToMsgId(SAMPLE_APP_HK_TLM_MID),
   			 sizeof(SAMPLE_APP_Data.HkTlm));
                
   

3. Create a pipe to the Software Bus (SB) by calling: CFE_SB_CreatePipe();
   

   /*
    ** Create Software Bus message pipe.
    */
   status = CFE_SB_CreatePipe(&SAMPLE_APP_Data.CommandPipe, 
                              SAMPLE_APP_Data.PipeDepth, 
                              SAMPLE_APP_Data.PipeName);
   if (status != CFE_SUCCESS)
   {
   	CFE_ES_WriteToSysLog("Sample App: Error creating pipe, RC = 0x%08lX\n", 
                            (unsigned long)status);
   }
   

   
   
4. TO SEE our messages, we have to subscribe to the SB by calling: CFE_SB_Subscribe();
   

   /*
   ** Subscribe to Housekeeping request commands
   */
   status = CFE_SB_Subscribe(CFE_SB_ValueToMsgId(SAMPLE_APP_SEND_HK_MID),
                             SAMPLE_APP_Data.CommandPipe);
   if (status != CFE_SUCCESS)
   {
   	CFE_ES_WriteToSysLog("Sample App: Error Subscribing to HK request, RC = 0x%08lX \n", 
                            (unsigned long)status);
   }
   

   
   

Now that our initialization is done, we can begin sending messages on the Software Bus anywhere in our application using one or more of the following three methods:

• Send a string or other data using the Software Bus module's CFE_SB_TransmitBuffer() method:
  

  /*
  ** Call CFE_SB_TransmitBuffer();
  */
  CFE_Status_t     CfeStatus;
  CFE_SB_Buffer_t *SBBufPtr;
  ...
  CfeStatus = CFE_SB_TransmitBuffer(SBBufPtr, false);
  if(CfeStatus != CFE_SUCCESS)
  { 
      // Create an error event using EVS (?)
      ... 
  }
  

  
  
• Send a message object using the SB's CFE_SB_TransmitMsg() method:
  

  /*  
  ** Send a message on SB using CFE_SB_TransmitMsg();
  */
  CFE_Status_t     CfeStatus;
  CFE_MSG_Message_t *MsgPtr
  ...
  CfeStatus = CFE_SB_TransmitMsg(MsgPtr, true);
  if(CfeStatus != CFE_SUCCESS)
  {
      // Create an error event using EVS (?)
      ... 
  }
  
  

  
  
• Finally, we have the option of placing a message on the SB incidentally by creating an EVS Event by calling: CFE_EVS_SendEvent();
  

  /*
  ** Place a message on the SB using CFE_EVS_SendEvent();
  */
  CFE_EVS_SendEvent(SAMPLE_APP_PIPE_ERR_EID,
                    CFE_EVS_EventType_ERROR,
                    "SAMPLE APP: SB Pipe Read Error, App Will Exit");
  

  
  
  

Summary / Conclusions

After using the four initialization steps (calls) above, we can place messages on the cFS local Software Bus (SB) using one or more of 3 methods.

Initialization calls:

1. CFE_EVS_Register();
2. CFE_MSG_Init();
3. CFE_SB_CreatePipe();
4. CFE_SB_Subscribe();

Normal Usage:

• CFE_SB_TransmitBuffer();
• CFE_SB_Transmit();
• CFE_EVS_SendEvent();

Sources

NASA, Fourier Automation