Custom View

Device Monitoring Studio supports parsing monitored packets according to a defined protocol (see protocol binding topic for details). After the packet is bound, values of packet fields are available for processing. The easiest way to see all field values is to use Structure View data visualizer.

However, if you want a better format for field values, use the Custom View data visualizer. It takes a special script file, written in TypeScript (a superset of JavaScript) which must be placed into the default protocols folder and its file name must end with .view.ts.

Custom View Workflow

When Custom View initializes, it loads a user-supplied script file and executes it. By convention, the user script should do nothing in a global scope and should not use global variables. Only declarations of different kinds are allowed at a global scope.

After the script execution ends, a following global function is invoked:

function createVisualizer(multiSession: boolean): ICustomVisualizer;

It is passed a single boolean argument which indicates whether this is a multi-source session or not.

The user script must initialize an instance of a class that implements the ICustomVisualizer interface and return a reference to it:

interface ICustomVisualizer {

    // Custom visualizer's name
    readonly name: string;

    // Custom visualizer's description
    readonly description: string;

    // A source type (a string) or types (string array). 
    // Supported types are "serial", "usb", "bridge" and "network"
    readonly sourceType: string | string[];

    // Optional error scheme ordinal. If omitted, defaults to zero
    readonly errorScheme?: number;

    // Return schemes used by this custom view
    getSchemes(): SchemeDefinition[];

    // Return a list of options supported by this custom view
    getOptions(): OptionDefinition[];

    // processPacket is called with each packet
    processPacket(packet: Object, isJoinPackets: boolean): void;
}

All interface members are mandatory and custom class must implement all of them. name should be set to unique custom visualizer name, which is later displayed in Protocols List Window. description is displayed to the user when he selects a custom visualizer from a list.

sourceType must be assigned a string that indicates the supported session type, that is, “serial”, “usb”, “bridge” or “network”. If the visualizer supports several session types, the property must be assigned to an array of strings indicating all supported session types.

getSchemes method is invoked to retrieve an array with all defined visual schemes. SchemeDefinition is defined as

interface SchemeDefinition {
    // Scheme name
    name: string;
    // Font face
    fontFace: string;
    // Font size, in pt
    fontSize: number;
    // Font weight is bold
    bold?: boolean;
    // Font style is italic
    italic?: boolean;
    // Text color
    color?: number;
    // Background color
    backColor?: number;
}

All fields are self-explanatory. Note that font size is in points and may be a non-integer number. Colors must be represented as a hexadecimal number in a form of 0xRRGGBB. Device Monitoring Studio internally stores the list of schemes and provides the user with an interface to change colors and fonts. Subsequently, custom script refers to the individual visual scheme by its ordinal number in an array returned by the getSchemes method. The array the method returns is required to contain at least one visual scheme.

Optional errorScheme property may specify the scheme ordinal to be used to display system error messages. If omitted, defaults to zero.

getOptions method should return (a possibly empty) list of user-controlled options for a custom view script. OptionDefinition is defines as

interface OptionDefinition {
    // Option friendly name
    name: string;
    // Default option value
    value: boolean;
    // Change function, called with a new value when user changes option
    change: (newVal: boolean) => void;
}

As with visual schemes, the list of options is stored internally and the user is provided with a way to change option values. Option values are allowed to be changed at any time and they are automatically applied with a call to the functor passed in a change property.

processPacket method is then invoked for each bound packet. A reference to a packet is passed in a first method argument, while the current state of a global “Join consequent packets” switch is passed in a second argument.

The following topic, the Visualizer Host describes the API available to custom view script to process and format packet data.