Skip to main content
Docs navigation

Plot any signal from C/C++ to your workspace

You already print values to see what your code does. gprintf is a printf that draws instead: swap one for the other, and the value shows up as a live time graph in your CppModel workspace while the program runs.

printf("speed=%f\n", speed);      /* before */
gprintf("motor.speed", speed); /* after: a live graph in the workspace */

It works in code that is already running: a bench program, a hardware-in-the-loop rig, a real-time loop, a long computation, a Python or Node.js script. There is no simulation to write, no step size and no end time. Each call records the value with the time it was made, and the library sends the values in the background, so a call never waits for the network.

gprintf needs SDK 0.18.0 or later.

An example​

A speed controller on a motor bench, logging its setpoint, speed and current every 10 ms:

#include <math.h>
#include <time.h>
#include <cppmodel/gprintf.h>

int main(void)
{
double speed = 0.0, integral = 0.0;
struct timespec tick = {0, 10 * 1000 * 1000}; /* 10 ms */

gp_init("motor-bench"); /* optional: names the stream */

for (int i = 0; i < 600; ++i)
{
double setpoint = i < 100 ? 0.0 : (i < 350 ? 1500.0 : 800.0);
double error = setpoint - speed;
integral += 0.02 * error * 0.01;
double voltage = fmin(fmax(0.05 * error + integral, 0.0), 48.0);
double current = voltage / 0.8 - speed / 400.0;
speed += (voltage * 60.0 - speed) * 0.01 / 0.4;

gprintf("motor.setpoint", setpoint);
gprintf("motor.speed", speed);
gprintf("motor.current", current);

nanosleep(&tick, NULL);
}
return 0;
}

Build it like any program that uses the library (see Installation), and run it. On its first successful send it prints where to look:

Stream: motor-bench, run ba06a433a55b5fad85a8e554e1faf618
UI: https://w12345.cppmodel.com/streams/motor-bench

Open the link while the program runs, and the graphs grow as the values arrive.

C​

#include <cppmodel/gprintf.h>. The header is self-contained over the library's C API.

CallDoes
gprintf(signal, value)Records value for signal now. Integers and booleans work too: they convert to double.
gp_init(name)Optional. Names the stream; call it before the first gprintf. Returns 1, or 0 with a message.
gp_init_with(name, flushInterval_ms, bufferSamples)The same, with the send interval and the samples kept per signal; 0 keeps the default.
gp_flush()Optional. Waits until everything logged so far has reached the workspace. Returns 1, or 0 with a message.
gp_shutdown()Optional. Sends what is left and closes the stream; it is also done at exit.

C++​

gprintf is in cppmodel/cppmodel.hpp and takes any arithmetic type. cppmodel::Stream names the stream and closes it when it goes out of scope:

#include <cppmodel/cppmodel.hpp>

int main()
{
cppmodel::Stream stream("motor-bench"); // optional; sends what is left when it goes out of scope

while (running)
{
// ...
cppmodel::gprintf("motor.speed", speed);
cppmodel::gprintf("motor.enabled", enabled); // bool, int, float, double...
}
stream.Flush(); // optional: wait until everything has been sent
}

Stream(name, flushInterval_ms, bufferSamples) takes the same settings as gp_init_with. It throws cppmodel::Error when the stream already started under another name.

Python and Node.js​

The cppmodel packages on PyPI and npm (see Python and Node.js) have the same two functions:

import cppmodel

with cppmodel.Stream("motor-bench"): # optional: names the stream
while running:
cppmodel.gprintf("motor.speed", speed)
const { gprintf, Stream } = require('cppmodel');

const stream = new Stream('motor-bench'); // optional: names the stream
gprintf('motor.speed', speed);
stream.close(); // optional: done at exit anyway

stream.flush() waits until everything so far has been sent.

The Streams view​

Streams have their own tab in the workspace, next to the simulations. It lists your streams, or your team's, with the status of each one's latest run: Live while the program runs, Finished when it ended normally, and Stopped when it stopped sending without ending, for example after a crash.

A stream's page draws its signals live, with the legend and the table view as for a simulation:

  • The graph refreshes about once a second while the program runs. Pause freezes it while you look.
  • Each run of the program is one run of the stream. When the program starts again, the new run replaces the old one on the page.
  • Values are joined by straight lines, not held as steps as in a simulation, because each one is a sample taken at its own time.
  • A NaN or infinity shows as a gap.
  • Copy the link to show a colleague the same live graph.

Windows and bands work here too. Log CppModel.Window.<name>.active to shade a phase, or CppModel.Band.<signal>.min / .max to draw a limit on a signal:

gprintf("CppModel.Band.motor.current.max", 40.0); /* the current limit, drawn on motor.current */
gprintf("CppModel.Window.ramp.active", ramping); /* shaded while ramping */

The motor bench above, with that current limit logged, shows where the start-up current goes over it:

motor.current with its 40 A limit drawn as a dashed line

Naming the stream​

A stream is named like a simulation, and the name is where its runs collect in the workspace. Without gp_init or a Stream, the first gprintf starts the stream without a name, and the workspace files it under the program's name (for Python and Node.js, the script's).

There is one stream per process, and each execution of the program is one run of it. Name it before the first gprintf: naming it afterwards, or with a second name, fails with a message and the stream keeps its first name.

Each run records the same identity as a simulation's execution: CppModel.BinaryFingerprint for the executable, and CppModel.GitHash for the commit it was built from.

How values are sent​

  • A call never blocks. gprintf puts the sample in a buffer in memory. A background thread signs in and sends the buffers every 500 ms, and once more when the program exits.
  • The buffer is bounded. Each signal keeps its last 10,000 samples until they are sent. If the workspace can't be reached for a while, the oldest samples are dropped, and the workspace reports how many.
  • Failures don't stop your program. When the workspace can't be reached, the samples are kept and sent again. When you aren't signed in, or the workspace doesn't accept streams, a message is printed once and the program carries on without sending.
  • Signing in works as for a simulation: the saved login, CPPMODEL_USERNAME and CPPMODEL_PASSWORD, CPPMODEL_ACCESS_TOKEN, or the browser prompt (see Running the simulation). It happens in the background.
  • Killed processes lose at most the last half second of samples. Call gp_flush() before something that may end the process.
  • A stream has at most 1,000 signals.

Turning it off​

Leave gprintf calls in the code and turn them off where you don't want them, for example in a production build or a CI job without credentials:

VariableDefaultEffect
CPPMODEL_STREAMonoff (or 0, false, no) discards every sample, without signing in
CPPMODEL_STREAM_FLUSH_MS500How often samples are sent, in milliseconds
CPPMODEL_STREAM_BUFFER10000Samples kept per signal until they are sent
CPPMODEL_STREAM_EXIT_TIMEOUT_MS5000How long a flush, or the send at exit, keeps trying

Settings given in code (gp_init_with, Stream(...)) take precedence over the environment.

gprintf or a simulation?​

gprintf shows what running code does. A simulation tests what code does, and is the better tool once you want a test:

gprintfSimulation
TimeWall-clock, as the program runsSimulated, in fixed steps, faster than real time
Code neededOne call per valueA step function, inputs and outputs
RepeatableNo: each run is whatever happenedYes: the same inputs give the same run
Pass or failNoPer step, with verification rules, as an exit code for CI
Inputs and parametersNot read from the workspaceSet in the workspace or from a file, without rebuilding
HistoryThe latest run of each streamEvery execution, compared across builds and commits

A common path is to start with gprintf on the bench to see the behaviour, then move the interesting case into a simulation, where it runs in CI and can't silently regress. A gprintf inside a simulation still goes to the process's own stream, with wall-clock times, not to the execution: record simulation values as outputs.