Debugging Guide

Pictorus is currently a free beta product, so we're expecting users to encounter plenty of fun bugs. Below are some helpful debugging suggestions that can help you track down the source of issues.

Tracing Broken and Orphaned Blocks

Pictorus is constantly re-evaluating your diagram to see what it can generate code for, and what it cannot. You can highlight issues by clicking the blue exclamation mark in the bottom-right. It will highlight any Broken (blocks with bad parameters or missing inputs) in red, and any Orphaned blocks (blocks affected by a Broken block) in orange.

broken and orphaned blocks

In the example above, we could see that the Product block was broken, since multiplication requires 2 inputs. By attaching another signal to it, the issue is resolved and the App compiles. By removing an input to the Sum block, new issues are reported and we can quickly identify them.

Debugging Apps on a Device

General hardware debugging guidance

Very often, especially when dealing with low-cost sensors and actuators, the problem is the hardware. As a reminder, please consider the following initial hardware debugging steps:

  • Check your wiring, and then check it again. Improper wiring is a huge cause of issues.

  • Check the manual. Sounds obvious, but lots of people skip this step. Very often devices have nuanced bootup/configuration sequences, or odd timing steps that must be executed precisely before the device will communicate properly.

  • Check all required protocols are enabled. Some protocols on some devices (like I2C on RaspberryPi) have to be manually enabled within the OS. Check if that is the case.

  • Does it work with a trusted Python script (or any other tool)? Many device manufacturers publish simple scripts online that can verify a device is working properly. If a well-tested script can’t communicate with your device, it’s unlikely Pictorus will be able to.

  • When in doubt, power-cycle! The old reliable medicine for a misbehaving computer. Should not be heavily relied upon, but even 21st century computers are still odd, stateful creatures who need to take a nap sometimes.

Unfortunately, it is sometimes the case that a device simply cannot be revived, especially a $3 servo motor. If you're completely unable to communicate with your device, there's not much Pictorus can do to help.

For devices which are online but behaving oddly, consider the following software debugging steps:

Viewing App Logs

After SSHing into your device. You should be able to see logs from the app and device manager using journalctl.

  • To see all logs: journalctl -u pictorus
  • To see recent log output in real time journalctl -u pictorus -f

These logs may reveal some telling errors, especially if the app is crashing or failing to initialize properly.

Running the app manually

You can also run an app outside of the device manager and manually pass in flags to make debugging easier.

  1. First make sure that the app is not running to avoid any resource conflicts.
    • You can do this by pausing the app from the UI, or by running sudo systemctl stop pictorus to kill the device manager and any associated processes. If you kill the app manager, make sure to start it when you're finished: sudo systemctl start pictorus.
  2. You can now run the installed app manually by running sudo /root/.pictorus/device_manager/apps/pictorus_managed_app

Debug logging

You can add the flag LOG_LEVEL=debug to print out extra information, including the value of each block at every time step. Warning: This generates a lot of verbose output, and can affect the performance of apps.

  • sudo LOG_LEVEL=debug /root/.pictorus/device_manager/apps/pictorus_managed_app

Recording data to a CSV

You can have the app output block values to a CSV file by setting APP_DATA_LOG_RATE_HZ=<rate_hz>, where the specified number is the maximum rate in Hz that the data will be logged. Data will be output to a file named diagram_output.csv in your current directory.

  • sudo APP_DATA_LOG_RATE_HZ=1 /root/.pictorus/device_manager/apps/pictorus_managed_app
  • This will only record data from blocks connected to a diagram output (such as plots or network/file IO blocks), so you will need to connect any blocks you're interested in to a Plot block.

Overriding block parameters

You can override parameters for any block in the diagram using environment variables. This can be done by locating the block ID (found in the lower right-hand corner of a block's setting panel),

Block ID

and then appending the name of the param you want to override. For instance: if I wanted to set the Amplitude of a block with ID = sinewave_123 to 42, I would add the flag SINEWAVE_123_AMPLITUDE=42 (note this must be all caps!) to the run command.

  • sudo SINEWAVE_123_AMPLITUDE=42 /root/.pictorus/device_manager/apps/pictorus_managed_app

Environment variables

There are other environment variables your App will respond to. Below is a list of them:

  • APP_DATA_LOG_RATE_HZ (default = 0): Sets the rate, in hertz (times per second), at which output data is logged to file. If the rate is 0 (as it is by default), no data output file will be created. An App cannot publish faster than its fundamental update rate (specified in browser).
  • APP_RUN_PATH (default = ""): The run path sets the local path where any assets generated by the app (i.e. the data log) will be stored.
  • APP_TRANSMIT_ENABLED (default = True): Enables/Disables any communication with hardware and protocols. When running in Simulation mode, for example, this prevents apps from attempting to communicate with non-existent hardware.
  • APP_PUBLISH_SOCKET (default = ""): Sets the UDP socket for communication with the Pictorus Device Manager.
  • LOG_LEVEL (default = INFO): Sets the logging level. Options are currently INFO and DEBUG. Info level shows very little logging, but will capture any major failure messages. Debug level dumps every single block’s value at every single time step. Use with caution!