Percepio Detect
---------------
Release 2025.1, April 15, 2025.


This is the main entrypoint for the Percepio Detect documentation.

It is recommended to start by running the included demo. 
Instructions are found in the Demo Guides:

    "Percepio Detect Demo Guide - Linux.pdf"
    "Percepio Detect Demo Guide - Windows.pdf"

This document provides an overview of the solution and describes the overall process
for how to integrate Percepio Detect to monitor your own system. 

More detailed documentation for each part is found in
 - readme-client.txt
 - readme-server.txt
 - readme-receiver.txt


Solution overview:

The Percepio Detect solution consists of four parts, with the following relations and data flow:

Percepio DFM library (on device) --> Percepio Receiver --> Percepio Server --> Percepio Client

- Percepio DFM
  The main target-side component of Percepio Detect. This outputs "alerts" on faults and
  anomalies, including debugging data from other supporting libraries. In the demo, the data
  is written to the serial debug console in real time but DFM can be customized to output the
  data using any interface and/or store them on the device.
	
- Detect Receiver
  Reads the device output, extracts the DFM data, converts it to the
  expected format and saves it as alert files for the Detect Server. This is a Python
  script and can be customized to accept any data encoding, e.g. Base64 or binary.
	
- Detect Server
  Reads alert files from Receiver and presents a summary in the web browser (the "Dashboard").
  Provides easy access to debugging data provided in the alerts, such as traces and core dumps.
	
- Percepio Client
  An integrated set of developer tools for debugging alerts, including Tracealyzer and tools
  for viewing core dumps. Runs on each user’s computer to make it easy to debug reported issues.


Data Storage:

All data is stored locally and is controlled by the customer.

The main data storage is the "alert directory", containing the alert files from the device.
For a multi-user setup, this is typically a shared folder on a file server or similar.

The Server also contains a database, that stores configuration and metadata, including the
relative paths to the alert files. This is generated from the alert files.


Typical Setups:

- Single-user setup: The Server, Client and Receiver runs on the same computer. Demo data is
  already provided in the test-data directory.

- The Server runs on a shared server. Each user runs the Client on
  their local development computer. The Receiver can run on any computer with
  access to the device output, for example a test computer with CI test runners.

To monitor multiple devices, you can have multiple Receivers running on the same computer
(one per device/connection). If needed, you can also run the Receiver on multiple lab computers,
each monitoring one or multiple devices.


Getting Started:

Start with the Demo guide matching your host operating system. This describes how to Detect
with the default single-user setup to view the bundled demo data.
    
    "Percepio Detect Demo Guide - Linux.pdf"
    "Percepio Detect Demo Guide - Windows.pdf"

To make a full setup including device integration, follow the steps below. 

Note that these steps are not strictly sequential and can often be performed in 
parallel by different team members to get started faster. The Server, Client and
Receiver can also be tested in isolation using the provided example data in the
"test-data" folder, as described below.

Target-side:

T1. Integrate the DFM library, CrashCatcher and TraceRecorder to your project
    as described in "device-integration/Percepio Detect - Device Integration Guide.pdf"

    Also see the demo project in device-integration/demo-projects. This is for an STM32L475
    device (B-L475E-IOT01A) and STM32CubeIDE. The source code demonstrates how to use
    DFM, TraceRecorder and CrashCatcher.

    There is also a brief document about Tracealyzer for Bare Metal systems in
    "device-integration/Tracealyzer Bare Metal Intro.pdf" with pointers to more
    detailed documentation.

T2. Instrument all relevant error handlers in your code to report errors as DFM alerts.
    Note that processor fault exceptions are captured automatically, assuming that the
    Device Integration Guide has been followed.

T3. Make test cases with DFM-generated alerts to ensure that the full Percepio Detect
    solution works as intended. For example, by causing a hard fault exception
    or by calling the DFM_TRAP macro.

Host-side:

H1. Set up the Server as described in percepio-server/readme-server.txt. 
    Make sure to update the BACKEND_IP variable in the Server start script with the IP address of the server.
    Notify your team members when it is ready and provide the server address.

H2. Set up the Client on a developer computer, as described in readme-client.txt.
 
H3. Set up the Percepio Receiver to provide the data transfer from device(s) to the server.
    See percepio-receiver/readme-receiver.txt for instructions.

H4. Finally, run your test cases (from T3) to verify that your alerts show up in the dashboard.
    Click on payloads to verify that you can view them in the Client.
   
    Finally, provide the Client and Receiver to your team, along with the Server address and port.


Retrieving build files in the Client:

The core dump viewer needs files from the build to display the data, at minimum the .elf file.
When you have alerts from multiple devices with different builds, the Client need to find the 
right version of the build files, matching the device that sent the alert. This can be achieved
by using the "revision" and "product" attributes in the client configuration. These are provided as
metadata in the alerts and are available in the Client, based on the selected alert.

If the build files are not available in your local file system (or in a network folder) you can
modify the "userdefinedhooks" script to download the build files from your build artifact storage,
for example using curl or wget.

See readme-client.txt for details.


Verifying the setup using Test Data:

You will find test data for the Server, Client and Receiver in the test-data directory.
This allows for verifying the setup of each part individually.

- Verifying the Receiver setup: 
  Edit the percepio-receiver script and set ALERTS_DIR to a suitable output path. The default input
  log file contains the demo alerts and writes them to the default alert directory. So running the
  Receiver again will duplicate the demo alerts. Choose a different output path to avoid that.

  Run the percepio-receiver script without arguments.
  Verify that you have a set of new directories with alert data in test-data/alert-files/DevAlert.
  There should be subdirectories following the structure <DeviceID>/<SessionID>/<AlertID>, 
  each containing several files like "1-1_da_header", "1-1_da_payload1_header", etc.

- Verifying the Server setup:
  Run the demo according to the Percepio Detect Demo Guide. This loads the provided alert files found
  in the test-data/alert-files directory. Open the server dashboard in the web browser and select the "Alerts" page.
  Click on Details for each alert. The Alert Key corresponds to a subdirectory of test-data/alert-files.
  Verify that all alerts in test-data/alert-files appear in the Alerts page listing.

- Verifying the Client setup:
  Run the demo according to the Percepio Detect Demo Guide. 

  Click one a core dump payload ("cc_coredump.dmp"). This should open a separate terminal window that shows the
  function call stack of the core dump, registers and other information.

  Click on a trace payload ("dfm_trace.psfs"). Percepio Tracealyzer should start and show the recorded trace.
  At the end of the trace, there is typically a "user event" (yellow label) showing "ALERT: <message>".
  
Notes:

* The Percepio Detect product is intended for use during development and testing, including 
  small-scale field testing. For observability in deployed production devices, ask Percepio
  for the DevAlert solution, intended for deployment. This uses the same core technology
  but requires custom integration for cloud-based data collection and storage.
  
* The solution is intended to run in a private, isolated network that is only available
  to trusted personell. There is no user management or authentication, so it must not
  be exposed to the public internet. It can be deployed in a private cloud environment
  assuming proper isolation from unauthorized access.
  
* By default, the server uses HTTP communication when accessing it at port 8080.
  Encrypted HTTPS communication is also supported by accessing the server at port 8081.
  This requires a certificate in the percepio-server/cert folder. 
  A self-signed cerificate is included as example, but this will give a warning in the
  web browser since not a CA-signed certificate.

* On Linux hosts, when using the Tracealyzer tool bundled in the Client, it can't show
  the User Manual or web links as there is no web browser in the Docker container.
  You can instead access the User Manual at http://localhost:8085/tz-user-manual/,
  assuming the Client is running and the Tracealyzer license has been installed.
   
For questions and assistance, please contact Percepio at 
 
     https://percepio.com/contact-us/

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

    
