Beep-Sat is a complete software example for a simple beaconing satellite that performs a handful of tasks and runs forever.

⭐ Software architecture that is easy to understand & build-upon

⭐ Well documented code with real-time debug messages

As introduced in ⚡Hands-On Quick Start, whenever a PyCubed board is powered, it loads and runs main.py from the board's root directory.

1. Blink LED task

Very simple task to blink the onboard RGB LED. With a priority of 255, Blink has a very low priority and will be preempted by most all other tasks.

2. Report IMU data task

This task demonstrates an important spacecraft function: how to perform routine sensor data collection over common serial buses such as I2C, SPI, or UART.

1. Each time the task is called, we create a dictionary (dict) object and populate it readings from the onboard IMU.

   readings = {
       'accel':self.cubesat.acceleration,
       'mag':  self.cubesat.magnetic,
       'gyro': self.cubesat.gyro,
   }

   • Although easy to understand, dynamically creating the readings dict every time we perform this task is not very memory-efficient. HOWEVER, CircuitPython's built-in "garbage collector" allows us to get away with things like this by automatically freeing memory when not needed.
   • The reason we create a dictionary (rather than a list or tuple) to store the data is 3-fold:
     1. Show how to define and populate a dict
     2. Have a dict ready to pass to the update method we are about to perform
     3. Aid us in printing a well-formatted debug message containing our most recent IMU readings
   • Each key in our dictionary (accel, mag, gyro) corresponds to an IMU reading. The IMU reading is collected using the self.cubesat.acceleration method which is a helper method from the pycubed.py library. The pycubed.py provides streamlined access to many hardware features. It's advised PyCubed users thoroughly review and understand the ⭐pycubed.py library.

     In this case, this method uses the IMU-specific library to request acceleration data from the IMU via I2C.

2. Next, we update another dict's existing key:value pair with our newly created readings variable.

   self.cubesat.data_cache.update({'imu':readings})

   • We update the data_cache dict because it is accessible via the self.cubesat object. This is useful because the self.cubesat object can be accessed from ANY task.
   • update is helpful because even if our data_cache dict doesn't have a key named "imu", it will create one and then update the values. It's also (relatively) fast since python uses hash matching for dicts.

3. Finally, we print the IMU readings by looping through the values of the newly updated "imu" key.

   for imu_type in self.cubesat.data_cache['imu']:
       self.debug('{:>5} {}'.format(imu_type,self.cubesat.data_cache['imu'][imu_type]),2)

   • We know the value of the "imu" key is another dictionary, so we use a for loop to access the keys (which are strings) for easy printing
   • We then format our debug message with some fancy alignment {:>5} and use the key name to access its respective value from the dictionary.
   • Passing a 2 as the second statement to our debug message tells it to put it on the second "level" which gives us the easy-to-read drop down formatting.

3. Monitor battery voltage task

Simple task that measures the battery voltage and compares it against a threshold. This shows you how to monitor the battery voltage and respond if necessary.

1. Start by using a pycubed.py helper function to measure the battery voltage and then store it as a variable called vbatt:

   vbatt=self.cubesat.battery_voltage

2. Compare our vbatt measurement to the self.cubesat.vlowbatt variable that was created when the board initialized. It's helpful to have vlowbatt stored within the cubesat object in case we ever want to change the threshold value (in another task perhaps) in response to something in our mission.

   if vbatt > self.cubesat.vlowbatt:
       comp_var = '>'
   else:
       comp_var = '<'

   • Update our variable called comp_var with the appropriate string
   • In the 📻Beep-Sat (advanced) demo, after this if statement is where we add important code to respond to a low battery condition.

3. Finish by printing the measured value as it compares to the threshold.

4. Report time since boot task

This task demonstrates some basic timekeeping by calculating how long this instance of the beep-sat code has been running.

1. Calculate time since boot

   t_since_boot = time.monotonic() - self.cubesat.BOOTTIME

   • time.monotonic() reports the time in seconds (float) since the PyCubed board was powered. This float will keep increasing until the board is power cycled or the microcontroller receives a hard-reset.
   • Since the pycubed.py library logs the time that the software boots (stored as cubesat.BOOTTIME, we can use that value to calculate how long this instance of the software has been running.

5. Transmit beacon packet & listen task

This task demonstrates how to transmit a message (using the default LoRa modulation settings) and then asynchronously listen for a response for 10 seconds.

1. Notice that before the main_task definition, we've set the attribute:

   schedule_later = True

   This is a built-in attribute (default=False) that tells the state machine to schedule the task for the first time after one frequency period has passed. So in this case, the beacon task will run for the first time at time=~30s.

2. First thing the task does each time it's called is check whether ANTENNA_ATTACHED is true or false. Since the ANTENNA_ATTACHED variable is local to the beacon task, this forces you to physically edit the file and set the value to True if you want the board to beacon.
   (make sure you've attached an antenna before trying to beacon)
   

3. If you've attached an antenna and edited the file accordingly, the board will transmit a beacon:

   self.cubesat.radio1.send("Hello World!",keep_listening=True)

   using the onboard RFM98PW radio. Radio modules have a lot of functions! Below are some resources to learn more about hardware and software capabilities.

   1. Understand the software capabilities by reading through the radio library located on your board at: /lib/pycubed_rfm9x.py

   2. Hardware capabilities of the radio can be found in the datasheet:
      
      🗄Component Datasheets

   3. Radio examples in 🖥️Code Examples

4. Regardless if we actually beaconed, we now want the radio to listen for messages and notify the state machine (without blocking other tasks) if it hears anything.

   heard_something = await self.cubesat.radio1.await_rx(timeout=10)

   ⭐ this await statement is the key to listening for messages without blocking other tasks

   • the code located below heard_something will not run until the the await statement returns. In the meantime, the code is able to yield and go back to performing other tasks.

   • we've built a timeout into the await_rx radio function to prevent the software from continuously checking for messages forever.

   Resources for understanding async behavior:

   1. The behavior is similar to Python's asyncio, but not exact!

   2. See the tasko library repo for more details

5. The beacon code "resumes" once heard_something has a value:

   if heard_something:
       response = self.cubesat.radio1.receive(keep_listening=False)
       if response is not None:
           self.debug("packet received")
           self.debug('msg: {}, RSSI: {}'.format(response,self.cubesat.radio1.last_rssi-137),2)
           self.cubesat.c_gs_resp+=1
   else:
       self.debug('no messages')
   self.cubesat.radio1.sleep()

   • if heard_something is True, that means await_rx has returned because the radio has received a message. So we retrieve the message, store it as response, and print it. We also increment our "response counter" register so we know how many times we've heard something.

     

     The "RSSI" value is a relative measure of signal strength.

   • heard_something is False when await_rx times out without receiving any messages

   P.S. This region of the code is where we implement over-the-air commands in the advanced example: 📻Beep-Sat (advanced)

6. Finally, whether we've received a message or not, we put the radio to sleep before ending this iteration of the task:

   self.cubesat.radio1.sleep()

Creating your own task

Adding a new task to the state machine is as simple adding a task file to the Tasks directory!

Receiving beacon packets and responding

An aspect of the Beacon Task discussed above involves listening for messages. But how can we transmit a message that our Beep-Sat will receive?

First we'll need another radio capable of transmitting a 433 MHz LoRa packet.

Below are some basic instructions for transmitting a messaging using each of the above options:

See 🖥️Code Examples for more radio examples.

Advanced features

The 📻Beep-Sat (advanced) demo builds upon what is established here by adding more hardware functionality, improved fault tolerance, over-the-air commanding, and more!