Plugins

This document provides comprehensive documentation for two visualization libraries: echelonic.planner.js for 2D floor plan editing and echelonic.map.js for 3D WebGL-based map visualization.

echelonic.map.js

echelonic.map.js is a high-performance, WebGL-based visualization tool for displaying 3D-extruded geofences, real-time tag locations, and heatmaps. It is designed to be highly configurable and interactive, with support for panning, zooming, rotation, and tilting via mouse, touch, and keyboard.

Quick Start

To get started, include the script in your project, create a container element in your HTML, and instantiate the map. Then, use the addLayer method to add a floor plan image.

HTML

<script src="echelonic.map.js"></script>

<link rel="stylesheet" href="echelonic.map.css"></link>

<div id="map-container" style="width: 100%; height: 600px;"></div>

JavaScript

// 1. Initialize the map
const map = new echelonicMap({
    // Required
    parentContainer: '#map-container',
    baseUrl: 'https://api.echelonic.cc/:site_id',
    authToken: 'YOUR_API_KEY',

    // Common options
    theme: '#0071e3',
    stats: true,
    heatmap: true,
    trailsEnabled: true
});

// 2. Add a floor plan layer and fit it to the geofences
map.addLayer('floorplan-1', 'path/to/your/floorplan.png')
   .fitToGeofences({ padding: 1.1, align: 'center' });

Configuration (Options)

The map can be configured by passing an options object to the constructor. Below are the available options, their default values, and descriptions.

Core Configuration

Appearance & UI

Initial View State

Controls & Interaction Toggles

3D Perspective & Tilt

Geofence Extrusion (3D)

Tag Marker Customization

Tag Trails

Heatmap Configuration

Public Methods

You can interact with the map instance programmatically using these public methods.

Map Instance Methods

Layer Instance Methods

The addLayer() method returns a Layer instance, which has its own chainable methods for configuration.

map.addLayer('floor-1', 'url/to/image.png')
   .setPosition(10, 20)
   .setSize({ width: 200 })
   .setOpacity(0.8)
   .show();

Controls and Interactions

The map supports a variety of interactions out of the box.

Mouse

• Pan: Left-click and drag.
• Rotate & Tilt: Right-click and drag. Alternatively, hold Ctrl or Alt while left-clicking and dragging.
• Zoom: Use the mouse wheel.
• Tooltip: Hover over a tag marker to see its ID.

Touch

• Pan: One-finger drag.
• Zoom: Two-finger pinch.
• Rotate: Two-finger twist.
• Tilt: Two-finger vertical drag.

Keyboard

• Rotate Left: Q key.
• Rotate Right: E key.
• Tilt "Up" (increase angle): W key.
• Tilt "Down" (decrease angle): S key.

UI Buttons

Control buttons appear on the map for easy interaction.

• Zoom In / Out: Adjusts the map's zoom level.
• Reset View: Fits all geofences into view and resets rotation and tilt to 0.
• View History: Opens a modal to select a date range. The map will then fetch and display a historical heatmap for that period, temporarily pausing real-time updates.

echelonic.planner.js

echelonic.planner.js is a feature-rich JavaScript library for creating interactive 2D floor plan editors. It allows users to place gateways, draw polygonal geofences, and measure distances. Also includes an RSSI-based fingerprinting toolkit for site surveys, a gateway signal heatmap, and a configurable measurement grid.

Quick Start

To get started, include the script in your project, create a container element in your HTML, and instantiate the planner with your required options.

HTML

<script src="https://unpkg.com/mqtt/dist/mqtt.min.js"></script>

<script src="echelonic.planner.js"></script>

<link rel="stylesheet" href="echelonic.planner.css"></link>

<div id="planner-container" style="width: 100%; height: 700px;"></div>

JavaScript

// Basic initialization
const planner = new echelonicPlanner(
    document.getElementById('planner-container'), 
    {
        // Required
        baseUrl: 'https://api.echelonic.cc/:site_id',
        authToken: 'YOUR_AUTH_TOKEN',
        map: 'path/to/your/floorplan.png',
        mapScale: 50, // 50 pixels = 1 meter

        // Common options
        colorScheme: 'teal',
        accentColor: 'orange',
        darkMode: true,
        
        // Required for fingerprinting
        mqtt: {
            brokerUrl: 'wss://your_mqtt_broker_url',
            topic: 'your/topic',
            tagId: 'YOUR_TAG_ID'
        }
    }
);

Configuration (Options)

The planner is configured by passing an options object as the second argument to the constructor.

Core & API Configuration

Appearance & UI

Fingerprinting (MQTT) Configuration

Grid Configuration

Pass a grid object in the options to customize the background measurement grid.

Public Methods

Controls and Interactions

• Pan: Click and drag on an empty area of the map.
• Zoom: Use the UI buttons, the mouse wheel, or a two-finger pinch gesture on touch devices.
• Add Gateway: Click the "Add Gateway" button, then click on the map to place it. A modal will appear to enter details.
• Add Geofence: Click the "Add Geofence" button. Click on the map to place vertices. To finish, click the first vertex again or click the "Confirm" button in the top-right controls. A modal will then appear for details.
• Select Item: Click on any gateway or geofence polygon/node to select it.
• Move Item: Click and drag a selected gateway or a selected geofence node to move it. If you move a gateway and fingerprint data exists, a warning modal will appear asking you to confirm, as this action invalidates the old data.
• Add Geofence Node: When a geofence is selected, small nodes will appear at the midpoint of each edge. Drag one of these to create a new vertex.
• Delete Item: Select an item (gateway, geofence, or geofence node) and click the corresponding "Remove" button that appears in the top-right controls.
• Measure Distance: Click the "Measure" button. Click a start point on the map, then move the mouse to see the live distance. Click a second time to finalize the measurement and exit the measurement mode.
• View Heatmap: Use the "Heatmap" dropdown to select an environment type (e.g., Office, Industrial). A heatmap visualizing the estimated signal strength from all placed gateways will be overlaid on the map.
• View Grid: A background grid representing meters can be displayed. It can be configured or disabled via the grid option during initialization.
• Fingerprint Collection:
  • Click the fingerprint icon to enter collection mode. A new panel will appear.
  • The panel will connect to the configured MQTT broker and display live RSSI readings from gateways for the specified tag.
  • Click anywhere on the map to select a location for a new fingerprint.
  • Click the "Record" button. The planner will collect several RSSI readings and save a smoothed value (using an Exponential Moving Average) for that point.
  • The recorded point will appear on the map. You can repeat this process for many locations.
  • To delete a recorded point, simply click on it, then click the "Delete" button.
  • Click "Update" to save all collected fingerprints to the server.
  • Click "Download" to export the fingerprint data as a JSON file.
  • Click "Close" or the main fingerprint button again to exit collection mode.