DTXr

{{>toc}}

h1. DTXr documentation

h3. Installation

* System Requirements

DTXr can run on any machine that can run +Java 17+ and has sufficient with RAM and disk capacity.

|Requirement|System RAM|System DISK|Example|

|Minimal|512Mbyte|512Mbyte|Raspberry 1, Raspberry Zero|

|Better|512Mbyte|512Mbyte|Rasberry Zero 2|

|Avarage|1GByte|1Gbyte|Raspberry 2-4|

|Top|2GByte|8Gbyte|Raspberry 4, Raspberry CM4, Server, PC|

* Network Requirements

DTXr can run stand alone without any active network connection. In that case the management pages is accessible via localhost interface. But for DTXr to be a fully functional BACnet/IP device it must be connected to an IP network that offers IP address via DHCP and where broadcast traffic is allowed.

* Download DTXr software packages

Currently only customers to DAVITOR can download DTXr. Contact info@davitor.com for purchase information.

* Install on Linux

** There is special install scripts, please follow these steps:

### Download latest DTXr _base_ image and copy to a SD-card that has 16Gbyte capacity or more

Or install a new image and install java

<pre>sudo apt install default-jdk </pre>

### Insert the SD card, attach keyboard and screen via cable and start the device

### When you get prompt login as **admin/davitor**

### Download the installation script from davitor repository 

*(note dtx.sh has an update since Jan 17th, 2024 see new parameter 'installfolder' below)*

*(note dtx.sh has an update since Nov 6th, 2025 see new parameter 'type' below)*

<pre>wget --user=**** --password=**** https://artifacts.davitor.com/repository/dtx-raw/scripts/dtx.sh</pre>

There is also a utillity script that can set the host name and MAC adress. Note, optional and only applicable on LION product appliances.

<pre>wget --user=**** --password=****  https://artifacts.davitor.com/repository/dtx-raw/scripts/system.sh</pre>

Make the scripts exec

<pre>sudo chmod 770 *.sh</pre>

### Run installation as below where you first alter:

*** Required type (-t type) where type can be "scriptengine" for small platforms like RpiZ with 32-bit OS or "polyglot" for any 64-bits OS like servers or PC.

*** Required version (-v x.y.z)

*** The the install folder (-f myfolder) Note: Still relative to /usr/local so (-f myfolder) results in /usr/local/myfolder/dtx...

*** Partner user name (-u ****)

*** Partner password (-p ****)

*** Application password for the HTTP interface login on port 9090 (-app-password xxxxxxx)

*** BACnet Decvice Id (bac-device-id=nnnnn)

*** BACnet password which you will use to control the BACnet device DCC (bacnet-password=xxxxxx)

*** BACnet Device Name (bac-device-name=yyyy)

*** DAVITOR Reference Key (drk=xxxx) is used to mange and maintain this device from the DAVITOR PLM (Product Lifecycle Management) service. (drk=xxxx) The sequence of drk:s is in PLM instance database.

*** Hardware Platform Type (platform=xx) is used to control and switch on/off special features that is hardware dependent.

For LION products use:

<pre>sudo ./dtx.sh -t scriptengine|polyglot -v 3.2.2 -f myfolder -u **** -p **** -s "bac-device-id=nnnnn bac-device-name=yyyy app-password=xxxxxx bac-password=xxxxxx lion-enabled=true drk=xxxx platform=XX"</pre>

For other installations like PC, Servers etc. use:

<pre>sudo ./dtx.sh -t scriptengine|polyglot -v 3.1.23 -f myfolder -u **** -p **** -s "bac-device-id=nnnnn bac-device-name=yyyy app-password=xxxxxx bac-password=xxxxxx drk=xxxx platform=XX"</pre>

### Utillity script to set MAC and host name

<pre>sudo ./system.sh -mac 70:B3:D5:16:E8:99 -hn DTX-L1-8R8DI</pre>

* Upgrade on linux

If you already have DTX installed and should upgrade to a new version *(Don't forget to set correct installfolder with -f)*

<pre>sudo ./dtx.sh -t scriptengine|polyglot -v 3.1.23 -f myfolder -u **** -p ****</pre>

* Manage the DTX service *(Note, since 17th Jan, 2024 of dtx.sh the names of the services are appended with the instsall folder in order to install multiple instances of DTX in same machine.)*

Stop<pre>sudo systemctl stop dtx_{myfolder}</pre> 

Start<pre>sudo systemctl start dtx_{myfolder}</pre>

Check status<pre>systemctl status dtx_{myfolder}</pre>

Disable service, wont start at reboot<pre>sudo systemctl disable dtx_{myfolder}</pre>

Enable service, will start automatically at reboot<pre>sudo systemctl enable dtx_{myfolder}</pre>

* For other Linux distributions follow this steps

### _TBD..._

* Install on Windows

** Follow these steps:

### _TBD..._

h3. LION Fieldbus

* See LION [[LION:Wiki]] for howto in installataion, channel assigmnets and testing.

---

h2. 1. Overview

h4. The DTXr web interface allows users to:

* View BACnet objects and their properties

* Modify writable properties (e.g., Present Value)

* Edit weekly schedules

* Switch between local and remote devices

* Monitor alarms, events, and notifications

* Use real-time updates through WebSocket (local device only)

---

h3. 2. Navigation Bar

h4. 2.1 Objects Menu

* *Refresh* reloads all object data and events.

_Note: Refresh is required when a remote device is selected._

h4. 2.2 Devices Menu

* Displays local device and all discovered BACnet devices.

* Devices are grouped by network.

* Selecting a device loads its object list.

h4. 2.3 Priority Menu

Controls the *BACnet write priority* used when writing Present Value.

Examples:

* Priority 1 – Manual Life Safety

* Priority 8 – Default

* Priority 16 – Lowest

h4. 2.4 Notifications Menu

Shows:

* Alarms

* Events

* Return-to-normal

The menu uses badge counters:

* Yellow = events  

* Red = alarms  

* Green = normal transitions  

---

h3. 3. Objects View

The main view lists all BACnet objects.

Features:

* Collapsible categories (accordions)

* Lazy loading of properties when expanded

* Editable Present Value fields where supported

* Real-time updates on the *local* device

* Manual refresh required for *remote* devices

h4. 3.1 Expanding an Object

Expanding an object loads:

* Properties

* Values

* Writable fields

* Schedule editor button (if applicable)

h4. 3.2 Writing Property Values

Steps:

# Edit a value in the input field.

# Press the Write/Save button.

# DTXr sends a BACnet WriteProperty with the selected priority.

# A popup shows success or error.

---

h3. 4. Device Discovery

h4. 4.1 Discovering Devices

Opening the *Devices* dropdown sends a Who-Is request and populates the list.

h4. 4.2 Selecting a Device

When switching devices:

* Properties reload

* Notification list reloads

* The selected device name appears in the navbar

h4. 4.3 Refreshing Content

*Mandatory* when using remote devices.

Use:

@Objects → Refresh@

This reloads:

* Object list

* Property values

* Notifications

---

h3. 5. Notifications and Events

Notifications include:

* Alarm

* Event

* Normal

Real-time updates:

* Enabled for local device

* Disabled for remote devices — manual refresh required

h4. 5.1 Acknowledgment

If a notification supports acknowledgment:

* Press _Acknowledge_

* DTXr sends BACnet AcknowledgeAlarm

* Notification updates when completed

---

h3. 6. Weekly Schedule Editor

h4. 6.1 Opening the Editor

Click the schedule property to open the weekly calendar modal.

h4. 6.2 Creating Events

Select a time in the calendar to create a new event.

h4. 6.3 Editing Events

Click an event to modify:

* Binary schedule → Active / Inactive

* Analog schedule → numeric value

h4. 6.4 Saving the Schedule

Click *@Save changes@* to store the weekly schedule.

The data is:

* Compiled into BACnet dailySchedule structures

* Sorted chronologically

* Sent to the device as JSON

---

h3. 7. Popups and Feedback

Popups indicate:

* Success

* Errors

* Info

* Warnings

---

h3. 8. Troubleshooting

h4. 8.1 Objects Not Updating

* Remote device selected → press Refresh  

* Network or device may be unreachable

h4. 8.2 Write Errors

Possible reasons:

* Incorrect priority  

* Object out of service  

* Invalid value  

h4. 8.3 Schedule Issues

* No events created  

* Missing object ID  

* Remote device requires manual refresh  

---

h2. Setup

DTXr is configured through the *Menu → Setup* page.  

All configuration settings are grouped into logical sections. Each section below provides a functional overview of what the user can configure.  

Values are stored in *settings.json* and applied system-wide after pressing *Save*.

*Important:*  

When a *remote device* is selected from the HUB interface, *a manual page refresh is required* to update configuration data.  

Local device information updates in real time.

h4. System

Contains all fundamental system-level access and identity configuration.

* Administrator Account  

  - Configure the password of the fixed “admin” user.  

* Operator Account  

  - Optional user with limited access for HMIs or machine operation.  

  - Username, password and start page can be assigned.  

* Developer Account  

  - Optional higher-level user with configurable module permissions  

    (code, objects, API, blocks, diagram, setup).  

* Logging  

  - Set the system-wide log level (Debug, Info, Warning, Error).  

* Hardware Platform  

  - Select hardware profile (PC/server, Mira/Mesh, LION, etc.).  

  - This controls the enable/disable state of platform-specific modules.

---

h4. BACnet

Defines all BACnet/IP protocol parameters for the device.

* Device Identity  

  - Device ID, Device Name.  

* Security  

  - BACnet password (used for Device Communication Control).  

* Protocol Settings  

  - Segmentation, Max APDU, Vendor ID and other low-level options.  

* Network Mode  

  - Basic IP communication behaviour (broadcast, BBMD usage when applicable).

This section is essential when integrating DTXr into a BACnet building automation network.

---

h4. Wireless Mesh

Provides access to the mesh radio configuration on supported hardware.

* Enable/Disable Mesh  

* Mesh Credentials  

  - Security keys, network key and authentication key.  

* Node Role  

  - Coordinator / Router / End Device.  

* Provisioning QR Code  

  - Device can generate a QR code containing mesh network credentials.

Note: Mesh options are disabled on platform types that do not support radio.

---

h4. Bluetooth

Configuration for onboard Bluetooth LE services (if supported by the platform).

* Bluetooth Console  

  - Enables BLE-based console output.  

* Beacon Mode  

  - Enables BLE advertisement and optional custom beacon name.  

* Address Visibility and Power Settings  

  - Controls how the device broadcasts itself to the environment.

These options are automatically enabled or disabled depending on the selected platform type.

---

h4. LION Interface

Shown only on LION-enabled platforms.

* Enable/Disable LION module support.  

* Hardware Extensions  

  - Configures behaviour of LION-specific IO hardware.  

* Channel Behavior  

  - Digital/analog features depending on LION product family.

---

h4. Davitor Advantage

Configuration for optional DAVITOR cloud lifecycle management.

* DRK (Davitor Reference Key)  

  - Used for remote maintenance and PLM link.  

* PLM Connectivity  

  - Service URL and communication settings when using cloud management.

---

h4. External Database Access

Lets the DTXr device communicate with an external SQL/NoSQL database.

* Connection  

  - Host, port and protocol information.  

* Credentials  

  - Username/password for authenticated connections.  

* Sync/Logging Options  

  - Defines how data is written externally (trend logs, events, custom data).

---

h4. File Integration

Tools for importing/exporting system content.

* Backup / Restore  

  - Download the current configuration or upload a saved configuration.  

* Project File Upload  

  - Add or replace project assets (HMIs, scripts, diagrams).  

* Logs  

  - Download generated logs for troubleshooting.

---

h4. HTTP Server

Controls how the embedded DTXr HTTP(S) service behaves.

* Port Configuration  

  - Default HTTP port is 9090.  

* HTTPS / TLS  

  - Optional encrypted access.  

* Session Timeout  

  - Auto-logout delay for inactive users.  

* Allowed Hosts  

  - Restrict network clients that can access the interface.

---

h4. Email

Allows the device to send or receive email for automation events.

* SMTP Server  

  - Address, port, TLS/STARTTLS.  

* Authentication  

  - Optional username/password.  

* Attachments Folder  

  - Path where incoming email attachments are stored.

---

h4. Location Services

The device can determine its location automatically.

* Automatic Geolocation  

  - Queries an external geolocation service to populate latitude/longitude.  

* Manual Input  

  - User can override location if browser access is restricted.

---

h4. IoT HUB (BETA)

Early-stage experimental cloud integration.

* Backend URL  

  - IoT gateway endpoint.  

* Device Token  

  - Authentication token for cloud usage.  

* Upload Options  

  - Define what data the device forwards (events, logs, telemetry).

---

h4. Save & Refresh

* Save  

  - Commits all modified settings to settings.json.  

* Refresh  

  - Reloads settings from device memory.  

  - Required after switching to a remote device.

---

h2. Blocks Editor (Blockly)

The *Blocks* page provides a visual programming environment based on Google Blockly.  

Users can build automation logic using drag-and-drop blocks instead of traditional code.  

All logic created here is converted into JavaScript and executed by the DTXr runtime.

The Blocks Editor is divided into four main areas:

* The *toolbox* (left side) containing categorized blocks  

* The *Blockly workspace* (center)  

* The *log and activity panels* (bottom)  

* Editor actions available in the top navigation bar

---

h5. Navigation Bar Features

* Blocks → *Refresh*  

  - Re-parses the block code displayed in the workspace.  

* Blocks → *Clear logs*  

  - Clears the log console in the footer area.  

* Test  

  - Executes the currently visible block code once, without saving.  

* Save  

  - Saves the current block workspace into the device configuration.  

* Activate  

  - Saves and also activates the block program so it runs continuously.  

* Notifications  

  - Shows system events, alarms, and normal transitions in real time.

---

h5. Blockly Workspace

The main canvas where blocks are placed and connected.

* Drag blocks from the toolbox onto the workspace.  

* Connect blocks to form logic chains.  

* Right-click a block to duplicate, delete, or collapse it.  

* Zoom and pan with the mouse wheel or gestures.

All changes in the workspace are local until *Save* or *Activate* is pressed.

---

h5. Toolbox Categories

The toolbox is organized into logical categories:

* JSON  

  - Blocks for constructing and parsing JSON objects.  

* Logic  

  - If/else, comparison, boolean operations.  

* Loops  

  - Repeat operations.  

* Math  

  - Arithmetic and numeric values.  

* Text  

  - String operations and concatenation.  

* Variables  

  - Create and manage global/local variables.  

*Events (DTX-specific)*  

  - Triggers for analog or binary input changes  

  - Astro events  

  - Timers  

  - Incoming text messages  

  - Diagram object push events  

*Set value / Read value (DTX BACnet extensions)*  

  - Write analog, binary, lighting outputs  

  - Read analog or binary values  

  - Compare input states  

*Timed tasks*  

  - Cron-like scheduling  

  - Start, cancel, pause, resume timers  

*HMI*  

  - Update graphical objects or maps in diagrams/HMI pages  

*Code*  

  - Insert raw JavaScript statements  

  - Create custom return statements  

  - Handle function call events  

*Misc*  

  - Print to log  

  - Date/time  

*Notifications*  

  - Send email from block logic  

These categories combine to cover automation, BACnet control, HMI interaction and notifications.

---

h5. Running and Activating Code

*Test*  

Executes the block logic one time, useful for debugging.

*Save*  

Stores the block script but does not run it automatically.

*Activate*  

Saves and deploys the block logic to the DTXr runtime engine.  

Activated logic will:

* Run automatically on device startup  

* Respond to events immediately  

* Allow scheduled logic to trigger without manual execution  

---

h5. Sidebars and Console

*Left Sidebar*  

May contain the workspace tree or additional contextual tools.

*Right Sidebar*  

Displays block metadata, help text or generated JavaScript depending on configuration.

*Footer Console*  

Two areas are available:

* *Log* — printed output from print blocks or runtime  

* *Activity* — messages about system behavior, activation, parsing, etc.

Both areas support resizing using draggable split panes.

---

h5. Working With Devices in Blocks Mode

The device selector is present but indicates:

*“Not applicable in Blocks mode”*

This is because Blockly logic always runs locally on the device that hosts DTXr.  

Remote devices cannot be programmed using the Blocks Editor.

---

h5. Saving Your Work

The block workspace is saved in the device’s internal configuration.  

A backup is included when exporting system configuration via the File Integration tools.

*Important:*  

If block logic interacts with remote devices (reading/writing values),  

use *Refresh* in Objects view to ensure the remote values have been updated recently.

---

h5. Error Handling

When errors occur:

* The error message appears in the log console  

* Pop-up notifications show parsing or execution issues  

* Common issues include:

  - Missing block connections  

  - Undefined variables  

  - Writing to unavailable BACnet objects  

---

h5. Best Practices

* Keep block structures grouped and well-organized  

* Name variables clearly  

* Use print statements during development  

* Test frequently before activation  

* Avoid long chains inside event triggers  

* Use timers for repeated actions, not loops

---

h2. BACnet

BACnet (Building Automation and Control Network) is an international open communication standard for building automation systems.  

It enables devices from different manufacturers to communicate, share data, and coordinate functions such as HVAC, lighting, alarms, access control and energy management.

BACnet is defined and maintained by the BACnet Committee (SSPC 135) under ASHRAE.

More information: https://bacnet.org

---

h3. Standards and Certification

BACnet is based on globally recognized standards:

* *ASHRAE Standard 135*  

  The core BACnet protocol specification, maintained by ASHRAE.

* *ISO 16484-5*  

  International standard for building automation and control networks.

* *ANSI/ASHRAE Addenda*  

  Regular updates ensure modern features and cyber-security enhancements.

Because BACnet is standardized internationally, devices are tested and validated against consistent technical rules.  

This ensures long-term compatibility and protects investments in automation systems.

---

h3. How BACnet Communication Works

BACnet defines:

* *Objects* — structured data models (AI, AO, BI, BO, Schedules, etc.)  

* *Properties* — attributes of each object (Present Value, Units, Status Flags…)  

* *Services* — methods for communicating (ReadProperty, WriteProperty, etc.)

Common communication mechanisms:

* **BACnet/IP** over UDP (default port 47808)  

* **Who-Is / I-Am** device discovery  

* **ReadProperty / WriteProperty** for data exchange  

* **COV (Change of Value) subscriptions** for event-driven updates  

* **Alarm and Event notifications**  

DTXr implements:

* Full BACnet/IP functionality  

* Device discovery  

* Automatic reading and writing of properties  

* Real-time event handling  

* COV subscriptions when available  

---

h3. Key Advantages of BACnet (Unique Selling Points)

*Open and vendor-neutral*  

BACnet is not controlled by a single private company. Any manufacturer can implement the standard.  

This eliminates vendor lock-in and ensures long-term system freedom.

*Large global ecosystem*  

Hundreds of companies worldwide produce BACnet-certified devices:

* HVAC controllers  

* Sensors and actuators  

* Lighting systems  

* VAV and damper controllers  

* Energy monitoring systems  

* User interfaces and visualizations  

This means integrators can mix-and-match equipment from different brands without special gateways.

*Interoperability by design*  

Because BACnet defines standard object types and required properties, devices share:

* Common naming conventions  

* Common alarm/event handling behavior  

* Standard scheduling objects  

* Standard data types  

This makes exchanging live data straightforward and predictable.

*Efficient Event-Driven Communication with COV*  

Rather than constantly polling for updates, BACnet supports **Change of Value (COV)** subscriptions:

* A device notifies subscribers only when a value *actually changes*  

* No wasted network traffic  

* Faster updates for dynamic values  

* Lower CPU and bandwidth usage  

* Ideal for large systems or wireless deployments

COV is one of BACnet’s biggest advantages over legacy systems that rely on heavy cyclic polling.

*Rich Metadata Built Into the Protocol*  

BACnet objects include a wide range of metadata:

* Object Name  

* Description  

* Units  

* Engineering limits  

* Reliability state  

* Status flags  

* Priority array  

* Object type  

Metadata allows tools like DTXr to:

* Auto-discover device capabilities  

* Display real names and units  

* Visualize systems without custom drivers  

* Auto-generate controls and dashboards  

This reduces engineering time and improves clarity for end users.

---

h3. Interoperability and Vendor Collaboration

BACnet has a long-standing interoperability testing ecosystem:

* *BACnet Testing Laboratories (BTL)*  

  Certifies devices against standardized profiles, ensuring correct communication.

* *BTL Listings*  

  Public database of certified devices that work together reliably.

* *Plugfests*  

  Manufacturers meet twice per year to test their devices against each other in real networks.

The result:

* Multi-brand BACnet systems work reliably  

* Integration cost is lower  

* Long-term compatibility is ensured  

* Devices can be replaced without redesigning the entire system  

BACnet is one of the strongest and most mature interoperability ecosystems in the automation industry.

---

h3. Why BACnet Works Exceptionally Well With DTXr

DTXr is built around BACnet’s strengths:

* Automatic discovery of BACnet devices  

* Real-time event and alarm handling  

* Full COV support  

* Multi-priority writing of Present Value  

* Automatic metadata integration (names, units, descriptions)  

* Native schedule editor compatible with BACnet Schedule objects  

* BACnet notifications shown directly in the interface  

DTXr can be used as:

* A BACnet central controller  

* A visualization/HMI layer  

* A programming environment (Code + Blocks)  

* A diagnostics tool for technicians  

* A multi-device integration and commissioning tool  

DTXr leverages the power of BACnet without requiring advanced protocol knowledge from the user.

---

* Davitor Advantage

** _TBD..._

* Wireless Mesh

** _TBD..._

* Bluetooth

** _TBD..._

* External Database Access

** _TBD..._

* File Integration

** _TBD..._

* HTTP

** _TBD..._

* LION Interface

** _TBD..._

* IoT HUB (BETA)

** _TBD..._

h3. User's Guide

h2. DTXr Web Interface – End User Documentation

*Important:*  

When selecting a *remote BACnet device*, the object list and notifications *do not update automatically*.  

You must press *@Objects → Refresh@* to reload the data.

For the *local device that hosts the web page*, all updates (property changes, events, alarms) are received *in real time*.

---

h3. Developer's Guide

[[IDE|IDE walk through]]

[[Javascript|The DTXr Javascript guide]]

[[Blockly|Blockly tutorials]]