SCOMTOOL user guide

Cross-platform utility for SCOM enabled devices

Introduction

SCOMTOOL is a swiss-army-knife tool for all SCOM enabled devices. An SCOM enabled device is a device, that supports the SCOM serial communication protocol, developed at the AGH University of Science and Technology in Krakow, Poland and licensed to EMBETECH.

How to get it

SCOMTOOL is distributed in a binary form. Here are the links to the direct download:

scomtool.exe ver. 1.0 for Windows 64-bit

scomtool.deb ver. 1.0 for Debian/Ubuntu arch:amd64

General usage

SCOMTOOL is a command line tool. It works by communicating with external hardware, connected through a serial port (physical or virtual) to the PC. The usage is generally:

scomtool.exe <args>

The following command line arguments are available:

-h : Prints help
-v : Prints version information
-s : Runs automatic scan on all available serial ports
-p PORT : Runs on a given port, in ex. COM12
-r : Resets the remote device using RTS line
-l : Resets the remote device using st-link command
-w PIN : Resets the remote device using gpio PIN
-d MS : Delays the program execution by MS milliseconds after reset
-o MS : Maximum timeout (in milliseconds) waiting for response from SCOM device while probing it for identity
-u FILE : Uploads FILE using SCOM Firmware Update service (if available in target device)
-t TEST : Runs a test using SCOM Test run service (if available in target device)
-x FILE : Sets custom tests results xml file name.
-f FILE : Sets group of parameters used in SCOM ETSI Test services using json file
-g : Outputs additional debugging information

Below is detailed explanation of all the usage possibilities

Printing help information

To get information about all possible command line arguments use the -h switch:

scomtool.exe -h

Printing version information

To get version information simply use the -v switch:

scomtool.exe -v

Running an automated scan on all available ports

The SCOMTOOL can run an automated check on all available serial ports, trying to identify SCOM enabled devices. It opens each available serial port and transmits a special SCOM packet (the so called IDENTIFY packet), that requests the device to identify itself. If a valid response is received, the port is considered to be active. Information about all SCOM enabled devices that has been found is then printed.

To run the automated scan use the -s switch:

scomtool.exe -s

Running the commands against all ports

The -s switch is also used to run other commands against all found devices.

Running against a specified port

In case when automated scan is not feasible, the SCOMTOOL can run against a particular device connected to a specified serial port. The -p switch is used for that purpose:

scomtool.exe -p COM12

Resetting the SCOM device

Many times it is feasible to reset the SCOM enabled device prior to using it. The SCOMTOOL supports three ways to reset the device, covering typical embedded development scenarios:

  • reset using the RTS line
  • reset using the ST-link
  • reset using the GPIO pin (only on platforms that support it)

To reset the SCOM device using the RTS line use the -r switch:

scomtool.exe -r -p COM12

To reset the SCOM device using the ST-link use the -l switch:

scomtool.exe -l -p COM12

The actual communication with the device may require additional delay after resetting. In such case use the -d switch, providing the time in milliseconds:

scomtool.exe -p COM12 -r -d 1000

Specifying SCOM communication timeout

In rare cases it might be important to specify the communication timeout, that is the maximum time spent waiting for the response from the device. This time (in milliseconds) may be specified using the -o argument:

scomtool.exe -p COM12 -o 300

SCOM services

The functionality of SCOM devices is enclosed in so called SCOM services. Each SCOM device may support multiple SCOM services. The following services are currently defined:

  • nameplate - allows to read out detailed information about the hardware and software
  • firmware update - provides a method of in-application firmware update
  • test run - allows to run unit test on the target platform
  • etsi test - allows to run ETSI related radio tests
  • configuration - allows to set application specific configuration

Running firmware update

The SCOMTOOL supports in-application firmware update through the use of SCOM Firmware Update service. The -u option allows to specify a file, that will be sent to the device as a firmware update. Typically, the device that that supports this service has a built in bootloader, that is invoked right after reset, so the procedure requires a reset. An exemplary command line that does exactly that is:

scomtool.exe -p COM12 -r -u my-update-file.rbt

Running ETSI tests

The SCOMTOOL supports the ETSI test SCOM service, designed to assist in running RED/EMC related tests of a radio-capable device. The radio capabilities of the device are always printed during scan, if the given device supports this service.

Due to the complexity of the ETSI test service, to actually use it is necessary to prepare a JSON file, with the description of functionality you want to achieve, basing on the ETSI test service specification. The JSON script is passed then to the SCOMTOOL using the -f option like this:

scomtool.exe -p COM12 -f script.json
Go to Top