LunatiX_0-1708524324321.png

ctrlX OS Diagnostic System: Use your own diagnostic messages

LunatiX
New Contributor

This How-to shows you how you could use your own diagnostic messages to support users while troubleshooting. We include a direct interface with the Data Layer (point 3), using Node-RED (point 4) and using PLC (point 5).

The ctrlX OS diagnostic system uses the linux service journald as logbook. Please have a look at the official documentation.

1. Prerequisites and equipment used 
  • Having a ctrlX CORE or ctrlX COREVIRTUAL with version => 2.4
  • Example with Node-RED: Node-RED app and basic Node-RED knowledge
  • Example with PLC: PLC app and ctrlX WORKS installed and basic CODESYS knowledge

2. Important Definitions

Logbook definitionsLogbook definitions

  • ERROR (0xF), WARNINGS (0xE) and MESSAGES (0xA) are available as class/type.

  • A main diagnostic (number and text) must be used.

  • A detailed diagnostic (number and text) is optional, but recommended.

  • Be careful with ERROR and choose the right priority for the status code, see definition.

  • User defined diagnostics must be provided by a JSON file. Note that each language (english, german, spanish, etc.) needs a separate JSON file. Following an example of a JSON file:

{
"product": "XCR-V-0114",
"mainDiagnostics": {
"0E0A0001": {
"text": "Successfully finished boot process",
"version": 1,
}
}
"detailedDiagnostics": {
"00000001": {
"text": "Finished boot process without errors",
"version": 1
}
}
}
 
3. Direct interaction with Data Layer - Diagnostic categories
3.1. «Fire and forget»

It can be set via Data Layer address diagnosis/set/set-and-reset

set-and-reset in datalayerset-and-reset in datalayer

Logbook example with a MESSAGE:

  • Only a log entry is created. MESSAGES are only set.

MESSAGE exampleMESSAGE example

Logbook example with a WARNING:

  • Only a log entry is created.
  • WARNINGS are immediately set and automatically deleted.

WARNING exampleWARNING example

Logbook example with an ERROR:

  • LED (ctrlX CORE light pipe) = blinking RED.
  • Framework state = ERROR.
  • ERRORS are set to the "inactive/reset" status. The errors have to be deleted separately. See below 3.3.

ERROR exampleERROR example

3.2. «Fire and remember»

It can be set via Data Layer address diagnosis/set/set-active. ERRORS and WARNINGS are given an active state and must be followed up. MESSAGES are not supported in this method since they do not need to be reset.

set-active in datalayerset-active in datalayer

Logbook example with a WARNING:

  • LED (ctrlX CORE light pipe) = blinking orange.
  • Framework state = WARNING.
  • Status: to fix within the logbook.
  • The warning must be deleted via method reset-active, see below 3.3

WARNING example (set-active)WARNING example (set-active)

Logbook example with an ERROR:

  • LED (ctrlX CORE light pipe) = blinking red.
  • Framework state = ERROR.
  • Status: to fix within the logbook.
  • The error must be deleted via method reset-active, see below 3.3.
  • The reset-active command generates a new error (but inactive), see below 3.3.

ERROR example (set-active)ERROR example (set-active)

3.3. «Error and warnings clearing»

a) Data Layer address diagnosis/set/reset-active.

  • Active WARNINGS will be cleared/deleted directly.
  • Active ERROR will be reset but a new inactive ERROR will be generated, which must be cleared via Data Layer address diagnosis/confirm/all-errors. 

b) Data Layer address diagnosis/confirm/all-errors.

  • Inactive ERRORS will be cleared.

Logbook example with a WARNING:

  • The warning will be cleared/deleted.
  • Status: changed from "to fix" to "occured" and a new entry with "solved" was generated.

WARNING example (after reset-active)WARNING example (after reset-active)

Logbook example with an ERROR:

  • Status: changed from "to fix" to "occured" and a new entry "to clear" was generated.

ERROR example (after reset-active)ERROR example (after reset-active)

  • Now the inactive error must be cleared/deleted (diagnosis/confirm/all-errors):

ERROR example (after ...confirm/all-errors))ERROR example (after ...confirm/all-errors))

  • Status: changed from "to clear" to "solved".
4. CODE example with Node-RED

We are including a Node-RED example with the following features:

  • Register and unregister a JSON file which contains the diagnostic definitions.
  • Create a MESSAGE, WARNING and ERROR.
  • Clear specific warning and error.
  • Clear all diagnostics.
4.1. Upload the JSON file via ctrlX OS WebUI

The main and detailed diagnostics are defined within a JSON file. This file has to be uploaded to the app data of the ctrlX CORE. You can do that easily via WebUI of the ctrlX CORE:

  1. Open the ctrlX OS WebUI and navigate to the manage app data.
  2. Open the File view.
  3. Create a new folder diagnostics.
  4. Upload the JSON file to this new folder.

After these steps it should look like this:

manage app datamanage app data

4.2. Import the Node-RED example and run it
  1. Open the Flow Editor from Node-RED and import the example code (JSON file).
  2. Do the setting for the Data Layer Request and Subscribe nodes.
  3. Deploy the program and open the dashboard.

After these steps you should be able to register/unregister the JSON file with the own messages and to set and reset errors, warnings and messages:

Node-RED dashboardNode-RED dashboard

5. CODE example with PLC

We are including a PLC example with the following features:

  • Register and unregister a JSON file which contains the diagnostic definitions.
  • Create a message, warning and error.
  • Clear specific warning and error.
  • Clear all diagnostics.
5.1. Upload the JSON file with PLC Engineering

The main and detailed diagnostics are defined within a JSON file. This file must be uploaded to the ctrlX CORE. The upload could be done with ctrlX PLC Engineering:

  1. Open your PLC Engineering project.
  2. Double click on the ctrlX CORE device.
  3. Go to tab Files.
  4. Host (left hand side): navigate to the directory, where you saved the JSON file.
  5. Runtime (right hand side upper corner): press the refresh button to see the existing files.
  6. Upload the JSON file.

After these steps the JSON file should be uploaded to the ctrlX CORE. See the picture below: 

tab Filestab Files

5.2. Import and run the PLC example
  1. Import the PLC example
    Click on Application, then on Project -> Import -> choose the provided *.export file. Then you should get these objects:
    PLC export dataPLC export data
  2. Call the program PRG_Diagnostics() in a cyclically program.
  3. Add the library CXA_DIAGNOSTICS.

    PLC Library ManagerPLC Library Manager
  4. Login and open the internal visualization.
    Here you can see several functions. Start with register the
    JSON file, after you are able to set/reset errors, a warning and a message.

    PLC visualizationPLC visualization
LunatiX
LunatiX
Hi, I'm Stefan from the DCEM Application Team. If you have any questions, do not hesitate to contact me.
Must Read
Icon--AD-black-48x48Icon--address-consumer-data-black-48x48Icon--appointment-black-48x48Icon--back-left-black-48x48Icon--calendar-black-48x48Icon--center-alignedIcon--Checkbox-checkIcon--clock-black-48x48Icon--close-black-48x48Icon--compare-black-48x48Icon--confirmation-black-48x48Icon--dealer-details-black-48x48Icon--delete-black-48x48Icon--delivery-black-48x48Icon--down-black-48x48Icon--download-black-48x48Ic-OverlayAlertIcon--externallink-black-48x48Icon-Filledforward-right_adjustedIcon--grid-view-black-48x48IC_gd_Check-Circle170821_Icons_Community170823_Bosch_Icons170823_Bosch_Icons170821_Icons_CommunityIC-logout170821_Icons_Community170825_Bosch_Icons170821_Icons_CommunityIC-shopping-cart2170821_Icons_CommunityIC-upIC_UserIcon--imageIcon--info-i-black-48x48Icon--left-alignedIcon--Less-minimize-black-48x48Icon-FilledIcon--List-Check-grennIcon--List-Check-blackIcon--List-Cross-blackIcon--list-view-mobile-black-48x48Icon--list-view-black-48x48Icon--More-Maximize-black-48x48Icon--my-product-black-48x48Icon--newsletter-black-48x48Icon--payment-black-48x48Icon--print-black-48x48Icon--promotion-black-48x48Icon--registration-black-48x48Icon--Reset-black-48x48Icon--right-alignedshare-circle1Icon--share-black-48x48Icon--shopping-bag-black-48x48Icon-shopping-cartIcon--start-play-black-48x48Icon--store-locator-black-48x48Ic-OverlayAlertIcon--summary-black-48x48tumblrIcon-FilledvineIc-OverlayAlertwhishlist