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

---

---

* BACnet

** _TBD..._

* 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]]