Video Tutorial: How to Set Up Traces and Alerts with Sternum

Amit Serper
Amit Serper

8  min read | min read | 04/05/2023

IoT devices are notoriously hard to monitor, often turning into complete “black boxes” as soon as they leave the factory floor.

We are here to change that. Using our Observability SDK, device builder (and their customers) can monitor embedded devices in real-time, in the field, with no performance tradeoffs.

In this video tutorial, we`ll show how you can use Sternum to granularly monitor every aspect of your device activity; CPU and memory utilization, temperature, battery status, BT connectivity, and more.

PS, to see how this technology helps solve real-world issues, check this webinar in which we talk to Medtronic about their use of Sternum to monitor & debug critical devices.

Hi, I’m Amit Serper and I’m the Director of Security Research here at Sternum.
In this video, I’ll show you how easy it is to set up a trace with Sternum ADS on an RTOS-operated device.

In this case, we have this STM 32 board right here. It’s running AWS freeRTOS firmware and we already have our sternum observability SDK loaded into our IDE. For those of you who don’t know Sternum, we are an embedded platform built for connected devices by augmenting every device with runtime security and granular observability. Sternum provides business insights, continuous in-field device monitoring, and built-in runtime security, enabling them to improve operational efficiency and achieve business excellence. To use Sternum monitoring we need to start with defining our traces, But before we start doing that, let’s first understand what traces are.

A trace is like a signal, an event or a log entry, something that we want the device to report back to ADS, for example, how the device is performing. What is its state? What is its configuration?
Another example could be performance information like CPU usage memory utilization or any other information that you’d like to monitor. It’s important to mention that you can also easily create alerts to monitor these traces and to get real-time notifications, but we’ll review this and more in our next video. So let’s get started. Here we have the device that I talked about earlier. This is the STM32 board that we are going to monitor, but in order to do that, we need to set up a trace. So let me show you how to set up the trace.

First, we need to download the studio app. You can download the studio app by going to the settings page right here and clicking one of those buttons which are relevant to whatever platform you’re working on. I’m working on Linux.  So I’m just gonna click the Linux button and I’m gonna download it and I’m gonna run it. OK?

So now that I have the studio app running right here, we can start setting up the traces. So first, if I’m a new developer for this project, I need to configure Studio on ADS and associate the device profile in the Studio app with my software project, which is on my hard drive. Basically, what’s going to happen is that the studio app will generate the trace definitions which are C-constant for our freeRTOS project.  And it’s going to create a file called trace_protocol_user_definition.h and this file is going to have all of these constants and we will include that file in our project. So we need to set up the Trace protocol user definition file for our studio.

In this case, I already did it before, but I’m just gonna clear it. This is the profile that I’m using for the free RTOS device. So I am going to click here on the path to the file and I’m going to type the location of where that file needs to be. And now we can see that it’s associated.

So we have the trace_protocol_user_definition.h file. We can see also that the status of this is ‘staging’ and I’m going to talk about that in a moment as well. But as of right now, we can actually start defining the traces. Once we have this file configured, we’re going to click and basically step into this device and look at all of the traces that are defined. You can see all of those traces right here. To add traces, the device from where it needs to be in the ‘development’ mode. So this is indicated by the state of the device profile as you can see right here in this column.

In our case, it shows ‘staging’, as I mentioned before. Now, ‘Staging’ means that the developers are still working on the code of the device and modifications are still possible. If the state here was shown as ‘Production’.  It would have meant that the code is frozen and the firmware can no longer be modified, but since we are still modifying our firmware and we’re still working on it and adding traces and adding some code, You can see that it’s still in ‘staging’ mode.

Now, let’s click and step into the device and look at all of the traces right here. And let’s talk about the types of the different traces.

As you can see here, we have system traces and we have custom traces. Now, the system traces, are basically preset by us, by Sternum, and have been added automatically. They can be used across all devices and cannot be modified. For example, the CPU or memory utilization uptime authentication or software upgrade-related traces.

Another type of traces are the custom traces. These are the traces that you can configure yourself for your own devices.  For example, the battery status, Bluetooth-related things, button presses, voltage, and so on And so forth. So in order to only see those custom traces, you need to click the custom button here and that will filter all of the custom traces. So we talked about traces, but there are also arguments. So let’s talk about arguments.

The trace itself may need to carry additional information such as the value of the data associated with the trace. For example, the value of the CPU utilization. So the percentage of the CPU usage or for example, which button was pressed. Let’s say that our board has multiple buttons like this one right here. If we add a trace to one button, we want to know which one of those two buttons were pressed. So we need to pass that as an argument. Such values are called trace arguments and they also need to be defined.

Each trace argument also has a unique name and we can see a few here. So we have pressure or MAC or security or channel or SSID. Each one of those is an argument that can be passed onto a trace.

Also a trace can have any number of arguments.

So let’s wrap this up in summary, if you think about a function in code, the trace would be like the function name and the argument would be like the function parameters.

Now let’s add a few traces and let’s go to custom traces, so we can trace some of those functions…

Ok, so we’re now going to define two traces and their argument, the first trace would be a temperature report and this one will tell us the value of the temperature sensor in Celsius and another trace that will report how the device is powered, for example, reporting the supplied voltage and power that the device is measuring or the status of the battery if it’s charging or or not.

So, so let’s add those traces! Let’s go here in the studio app. I’m going to click this plus icon right here on the right-hand side of the screen and I’m going to add the trace.

Let’s add those traces. First, we’re going to do the temperature report. So temperature report and let’s add the second trace which is battery status. Both of those are now populated here. Let’s click ‘add’ and Boom, we’re done!

So if we’ll search for them, let’s search for the temperature report. It’s right here and let’s look for the battery status.

Now, let’s add those arguments that we’ve just talked about, right? So again, very similar, we’ll switch to the arguments. We’ll click the plus icon on the right-hand side of the screen and we are going to add those traces. So we have ‘temprature c’. That’s one argument and we have ‘battery is charging’, that’s the second argument and we have ‘battery level’, that’s the third one, and we have ‘battery voltage’, that’s the fourth one.

So now we’re gonna click “Add” and we can see that they’re here: ‘batteries charging’, ‘battery voltage’, ‘battery level percent’, all of those values that we’ve talked about are now here. Now let’s jump to the IDE and see how we can implement all of those things in our code. OK?

So now we’re here in my IDE, I’m using VS code as you can see. And now after we’ve defined those traces in the studio app, we can go ahead and implement them here in our code…

I spared you the immense pleasure of seeing me typing all of these lines of code. So I already added them before and I commented them out. So I’m gonna go over it real quick on what we have here because this is actually the implementation of the Sternum collection right here. So if you remember before, I mentioned that there are prebuilt traces and there are custom traces.

So I’ve already included some prebuilt traces here such as the CPU usage trace. Let’s go and uncommon this guy right here. So you can see that we are calling the Sternum ADS trace function and we’re passing it to relevant parameters which are the trace CPU usage and the arguments which is the percent of the CPU usage. So this is one thing that we’re going to collect… Another prebuilt trace is the memory usage trace, which will tell us basically what is the percentage of used memory on the device.

So again, same thing Sternum ADS trace and then we’re calling the memory usage trace and passing the argument which is the percent. So let’s uncommon this guy right here. And now for the custom traces that we’ve added a moment ago. So we’re gonna start with the temperature report that we’ve just added. So again, Sternum ADS trace, which gets the trace temperature report trace that we’ve created in the studio app. There’s a space here.

And then we’re going to add as an argument, we’re going to add the temperature in Celsius to that function. So again, let’s comment that and there is another custom trace right here, which is for the battery status. So, in the battery status, we’re tracing or rather collecting three items. The first item is whether the battery is, is charging or not. So we can see is battery charging.
So we are going to collect that again, same thing, Sternum ADS trace and then we’re passing several arguments and a trace can have as many arguments as you want. It can have one argument and it can have 10 or 20 as many as you want.

So, in this case, we’re passing three arguments. The first argument is whether the battery is charging or not. The second one is the battery level percent and the third one is the voltage, right?
So I’m just going to uncommon those real quick and I’m going to save it and now I’m going to pause my recording. I’m going to compile this code. I’m going to flash the board and then I’m gonna come back and I’m gonna show you how this data looks over at ADS at our web-based platform where all of the data is being shown. So I’ll be right back once this is built.

So now we’re back in ADS and we have our data reported and a lot of the traces were captured and instrumented and we can now see them here on the system.

So for example, you can see all of those CPU usage traces that we have defined before. And you can see that in, at this point in this, we can see that at 18:09, we had a few measurements of the CPU usage. So you can see that here that it’s going all the way from 11% usage to 12 to 31 to 26 to 20 we can see other traces here as well.

For example, in the battery trace that we added, we can see here that the battery is not charging. The battery level is at 51 the voltage is at 12.7.

Now, there are a lot of other traces that we can take a look at, here in the system. We can actually also go into a trace event and see a whole timeline of what happened around the time when a certain trace was captured. So we can see here that right before this battery status trace was captured. There was also an authentication status trace that was captured and another CPU usage and so on and so forth. So now that this data is on ADS, it opens many interesting opportunities for how to use this data. But we will also cover this in our next video.

Before I go, I just want to show you this screen, this is the ‘Glances’ screen where you can see your device traces visualized. In my next video, I will show you how you can create custom alerts, get insights about your device or device fleet, and get alerted on an unusual product or user behavior. Just before we wrap up, if you want to learn more about some specific interesting use cases that our users had I invite you to watch the video in the link below and to see how Medtronic is monitoring their devices using Sternum.

Webinar: How Medtronic Secures, Monitors & Debugs Critical Devices

So I’ll see all of you with more cool stuff in our next video.


Enter data to download case study

By submitting this form, you agree to our Privacy Policy.