Percepio Receiver
-----------------
Release 2025.2, Sept 24, 2025.

This tool reads a log file from a device containing the DFM library, i.e. the target-side
component of Percepio Detect. It identifies any alert data from DFM and stores it as alert files,
intended for ingestion by the Percepio Detect server.

This tool requires that you have python installed and accessible from the command line.

A demo script is provided in receiver-demo.bat/.sh. This script takes no arguments.
It calls the Receiver script with the demo log file as input and writes the new alert files
to the default alert directory, so it shows up in the dashboard.


Usage:
- On Linux: ./percepio-receiver.sh [arguments]
- On Windows: percepio-receiver.bat [arguments]

  Arguments:
     <inputtype> := txt | bin    The type of data: txt = output format of "Serial" module, bin = binary DFM data (e.g. from ITM module).
     -i, --inputfile <file>      The file to read, containing DFM data in the specified format (bin or txt).
     -f, --folder <dir>          Where the alert files should be saved (the server's alert directory)
     -e, --eof <wait|exit>       What happens when reaching end of file: exit (default) or wait for more data (then exit by Ctrl-C).
     -d, --device_name <string>  If device name is not specified in DFM, set it here.
     -v --verbose                Shows (very) verbose output, useful for troubleshooting.

Usage examples for Windows
On Linux, just replace .bat with .sh.

 - percepio-receiver.bat (no arguments)
   Prints usage help.

 - percepio-receiver.bat bin --inputfile dfm.bin --folder ../detect/alerts --device_name MyBoard123 --eof wait
   Loads a binary data file and waits for more data until closed with Ctrl-C.
   The Device ID is updated to "MyBoard123", unless already specified in the 
   target-side DFM library.

 - percepio-receiver.bat txt -i dfm.log -f ../detect/alerts -d MyBoard123 -e exit  
   Loads textual log file and exits when done. Also Updates Device ID like in the previous example.
   Using the short arguments instead.

The device_name parameter is optional. If you choose to initialize the DFM library on the device 
using the simplified option xDfmInitializeForLocalUse(), you are not required to specify a unique
device name in the DFM config. In that case, DFM provides placeholder device name. In that case,
you may use the device_name argument to overwrite the device name.


Notes: 

 * Accepted input formats, must be specified as the first parameter
  
  - INPUTTYPE: bin
    Binary files containing raw DFM entries, i.e. the data chunks provided to the DFM output module.
    The file may contain other data in between the DFM entries (ignored and causes no error).
    Incomplete DFM entries are discarded.

  - INPUTTYPE: txt
    Textual log files from the DFM \"Serial\" module, for example
    [[ DevAlert Data Begins ]]
    [[ DATA: D1 D2 D3 D4 F0 0F ... ]]
    [[ DATA: ... ]]
    [[ DevAlert Data Ended. Checksum: 0 ]]
    
 * Checksum 0 from DFM means "no checksum provided". This makes the Receiver skip checksum verification. 

 * In case you are curious about the directory structure created by the receiver (and expected by
   the server and client), the structure has the following meaning:

      DevAlert/DeviceID/SessionID/AlertNumber/AlertFile
  
      - DevAlert: A constant identifying the root folder of an alert directory. Expected by the Server and Client.
      - DeviceID: A unique identifier of the device. Can be provided in DFM or in the device_name parameter of percepio-receiver.bat or .sh.
      - SessionID: A unique identifier of the current session, i.e. the activity in between device restarts. The Receiver sets this automatically using a host timestamp if not specified in DFM.
      - AlertNumber: The number of the alert within the current session (since last restart of the device).
      - AlertFile: A DFM data chunk, either the main alert header, a payload header or a payload data chunk (can be several). These are read by the Server and Client to display the alert data. 

 * If the device library (DFM) has been initialized using xDfmInitializeForLocalUse(), the
   current host time is used as SessionID. This avoids the need to implement a unique SessionID
   in DFM. This may however produce duplicated alerts if the receiver is run multiple times on the
   same input file.

For questions and assistance, please contact Percepio at https://percepio.com/contact-us/

Copyright (c), Percepio AB, 2025
https://percepio.com

    
