AWS Open Source Blog

Diagram Maker: Open sourcing IoT visualization

Today we are announcing Diagram Maker, an open source graphical user interface library for IoT application developers. With Diagram Maker, IoT application developers can define their own user interface and user experience, or suppress it completely and build their own custom behavior using Diagram Maker APIs. In this post, we explain how IoT application developers can get started and contribute to the open source project for Diagram Maker by using the Diagram Maker’s plugin interface to author reusable plugins.

What is Diagram Maker?

Diagram Maker is an open source client-side library that enables IoT application developers to build a visual editor for IoT end customers. With this visual editor, IoT customers can create and modify any graph-like data, such as state machines or workflow definitions, in a visual manner with the help of graphical UI.

Here is an example of JSON that describes a state machine built inside IoT Events:

{
    "detectorModelDefinition": {
        "states": [
            {
                "stateName": "Charging",
                "onInput": {
                    "events": [],
                    "transitionEvents": [
                        {
                            "eventName": "Full_charge",
                            "condition": "$input.AWS_IoTEvents_HelloWorld_VoltageInput.voltage > 29",
                            "actions": [],
                            "nextState": "Charged"
                        }
                    ]
                },
                "onEnter": {
                    "events": []
                },
                "onExit": {
                    "events": []
                }
            },
            {
                "stateName": "Charged",
                "onInput": {
                    "events": [],
                    "transitionEvents": [
                        {
                            "eventName": "In_use",
                            "condition": "$input.AWS_IoTEvents_HelloWorld_VoltageInput.voltage < 29 && $input.AWS_IoTEvents_HelloWorld_VoltageInput.voltage > 20",
                            "actions": [],
                            "nextState": "Discharging"
                        }
                    ]
                },
                "onEnter": {
                    "events": []
                },
                "onExit": {
                    "events": []
                }
            },
            {
                "stateName": "Discharging",
                "onInput": {
                    "events": [],
                    "transitionEvents": [
                        {
                            "eventName": "Charge_on",
                            "condition": "$input.AWS_IoTEvents_HelloWorld_VoltageInput.voltage < 21",
                            "actions": [],
                            "nextState": "Charging"
                        }
                    ]
                },
                "onEnter": {
                    "events": []
                },
                "onExit": {
                    "events": []
                }
            }
        ],
        "initialStateName": "Charging"
    },
    "detectorModelDescription": "A sample \"Hello_World\" detector model that monitors powerwall voltage.",
    "detectorModelName": "AWS_IoTEvents_Hello_World",
    "evaluationMethod": "BATCH",
    "key": "powerwallId",
    "roleArn": "arn:aws:iam::XXXXXXXXXXXX:role/service-role/AWS_IoTEvents_HelloWorld_ActionRole"
}

A screenshot of three states from IoT Events console:

A screenshot of three states from the IoT events console.

The idea of an open source UI library for building IoT applications isn’t entirely new. There are libraries already existing in the open source community for non-IoT use cases, providing low-level abstractions of drawing lines and shapes without built-in interactions. There are also libraries that provide high-level abstractions, such as nodes and edges. However, these libraries cannot easily be integrated into different IoT applications.

Note: In this post, edge refers to the geometric line that connect two vertices.

Diagram Maker offers a visual experience that is not only consistent with the host application, but also provides application developers more room to come up with their various look and feel with the host application. Released under an Apache 2.0 license, Diagram Maker provides high-level abstractions, such as nodes and edges, and still retains a high level of customization, both in terms of look and feel, and in terms of user experience.

At its core, Diagram Maker comes loaded with features, such as:

  • Built-in node dragging
  • Drag to create edges
  • Canvas panning & zooming
  • Panel dragging
  • Context-based menu
  • Keyboard shortcuts for selecting all and deleting
  • Modes: dragging mode, selection mode for multi-select, read-only mode for restricting edits
  • Declarative interface for defining any drag and drop interfaces, such as panel headers or node connectors

With Diagram Maker, IoT application developers can create, move, or delete nodes and the edges. These could represent different entities based on the AWS IoT service. For example, in AWS IoT Events, a node represents a state, and an edge (the geometric line that connect two vertices) represents a transition. Developers can model the location and sizes of nodes, edges, and panels, and Diagram Maker renders these as elements on the Diagram Maker canvas. The rendered UI is fully interactive and lets users move nodes around, create new edges, or delete nodes or edges.

Diagram Maker comes with the ability to automatically lay out a given graph via an API interface. With this API interface, application developers can now undo or redo mutative actions, fit all the nodes inside the view, focus given or selected nodes, and create layouts. With this feature, application developers can easily visualize the relationships by having the layout-related information attached with the resources, even if they are created outside the editor.

Furthermore, application developers can potentially leverage Diagram Maker’s capabilities for use cases outside of IoT. For instance, with Diagram Maker, application developers can enhance the experience for end customers by enabling them to intuitively and visually build cloud resources required by cloud services such as Workflow Engines (AWS Step Functions) or Infrastructure as Code (AWS CloudFormation) to get the relationships and hierarchies working.

Getting started with Diagram Maker

Diagram Maker is available in GitHub.

Diagram Maker plugin: Minimap

Alternatively, IoT application developers can use the Diagram Maker’s plugin interface to author reusable plugins. Reusable plugins developed by application developers extend the Diagram Maker’s core features so that end customers can use plugins without needing to develop such functionalities themselves.

Along with Diagram Maker, we are also open sourcing the minimap plugin, the first plugin made on top of the Diagram Maker plugin interface. The minimap plugin allows consumers to render a small minimap within a panel of their choice. This is helpful when IoT customers are working on a large graph with hundreds of nodes where navigating this graph becomes complex. The minimap enhances the customer experience by showing an overview of the entire graph and lets customers drag and click on different parts to directly jump to those parts of the canvas.

Screenshot of the minimap plugin experience of displaying the entire graph.

We envision this initiative to grow to a vibrant community of plugin authors who would extend Diagram Maker’s core functionality in innovative ways. These will in turn benefit all consumers of this library both within AWS IoT and other products, and will help our IoT customers make sense out of their IoT data quicker and easier.

Conclusion

Making Diagram Maker an open source project fosters innovation and provides a greater value for our customers. Developers have complete control over defining the interface and user experience. With such extensive features at its core, Diagram Maker allows the IoT application developers to modify Diagram Maker behavior, suppress it completely, and build their own custom behavior using Diagram Maker APIs, or using the Diagram Maker’s plugin interface to author reusable plugins. As a community, AWS and IoT application developers can together provide value to IoT end customers.

Sid Ilangovan

Sid Ilangovan

Sid is a Senior Product Manager for AWS IoT Analytics Services. He loves empathizing with customers and crafting enjoyable product experiences. He also draws, does photography, and occasionally enjoys long distance motorcycle rides.

Sameer Goyal

Sameer Goyal

Sameer Goyal is a senior engineer at AWS. He joined AWS in 2017 and worked on the management console for AWS IoT and related services for a couple of years before moving on to help with building AWS IoT SiteWise Monitor. Currently, he is working within the AWS AI organization on Rekognition and related services.