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.

h3. Setup

DTXr is setup via Menu -> Setup page.

* System

** Administrator password - Password for the default (and not changeable) account  **"admin"**. Default is **"davitor"**.

_When you log in you will start att /home/admin

There is another user "pi" as well with a secret password._

** Operator username - Username for the typical user of any HMI developed on this device. Typically a machine operator. [Optional]

** Operator password - Password for the operator user. [Optional]

** Operator start page - Set any web page in the project folder that will automatically shown on an operator login. [Optional]

** Log Level - The system severity level for the system_app.log in /Logs tree directory.

** Platform - This is where DTX gets its information on which hardware options to consider.

h2. Setup – User Documentation

The Setup page allows configuration of all core DTXr system features such as passwords, BACnet parameters, hardware platform settings, networking, database access, and optional communication modules.

Below is a hybrid overview:

* A short end-user summary for each section

* A detailed field explanation block beneath each one

---

h3. Details

This section contains general device settings such as administrator credentials, operator account configuration, logging, and hardware platform selection.

*Summary:*

* Change admin and operator credentials

* Define operator start page

* Adjust system log level

* Select hardware platform profile

*Details:*

** Administrator password  

The password for the fixed “admin” account used to log into the main system.  

** Operator username  

Optional secondary user for HMI applications.  

** Operator password  

Password for the operator user.  

** Operator start page  

Defines which page is shown after operator login.  

** Log Level  

Controls verbosity for system_app.log (Error / Warning / Info / Debug).  

** Platform  

Hardware profile used to enable/disable platform-specific features (LION modules, radios, etc.).  

---

h3. BACnet

This section configures the device’s BACnet server identity and behavior.

*Summary:*

* Set device ID, device name, and BACnet password

* Configure network parameters such as segmentation and APDU size

* Enable/Disable BBMD (if available)

*Details:*

** Device ID  

Unique BACnet device identifier (required).  

** Device Name  

Human-readable device name.  

** BACnet Password  

Used for Device Communication Control (DCC).  

** Max APDU / Segmentation / Vendor ID  

Low-level protocol options.  

** BBMD Settings  

Optional Broadcast Management configuration for routed networks.  

---

h3. Davitor Advantage

Provides settings for cloud-based lifecycle management integration.

*Summary:*

* Configure access to Davitor PLM services

* Set DRK (Davitor Reference Key)

*Details:*

** DRK  

Used for secure PLM registration and remote management.  

** PLM Connectivity Settings  

Optional service endpoints and credentials.  

---

h3. Wireless Mesh

If the platform includes wireless mesh capabilities, configuration appears here.

*Summary:*

* Define mesh network parameters

* Enable/disable mesh module

*Details:*

** Mesh Role  

Defines node type (Coordinator / Router / End Device).  

** Channel / PAN ID  

Mesh frequency and network identifiers.  

** Encryption Key  

Optional security layer.  

---

h3. Bluetooth

Used to configure Bluetooth LE functionality on supported hardware.

*Summary:*

* Enable/disable Bluetooth

* Configure advertising name and pairing mode

*Details:*

** Bluetooth Enabled  

Turns the module on/off.  

** Device Name  

Shown during discovery.  

** Pairing / Security  

Optional pairing settings.  

---

h3. External Database Access

Allows the DTXr device to interface with an external SQL or NoSQL database.

*Summary:*

* Configure connection strings, credentials and modes

* Used for logging, trend storage or custom applications

*Details:*

** Database Type  

(MySQL / Postgres / SQLite / Other).  

** Host / Port  

Server location.  

** Username / Password  

Login credentials.  

** Sync/Logging Options  

Frequency of writes, table naming, etc.  

---

h3. File Integration

Allows importing or exporting configuration files, logs, or scripts.

*Summary:*

* Upload/download device configuration

* Export logs

* Provide custom scripts or HMI assets

*Details:*

** File Browser  

Shows files stored on the device.  

** Upload Section  

Allows uploading project assets.  

** Backup/Restore  

Download configuration or upload a saved configuration.  

---

h3. HTTP

Defines HTTP server behaviour for the web interface.

*Summary:*

* Configure ports, HTTPS, session timeouts, and login settings

*Details:*

** HTTP Port  

Default: 9090.  

** HTTPS Enable  

Optional TLS enablement.  

** Session Timeout  

Idle logout time.  

** Allowed Hosts  

Restrict which IPs may contact the web server.  

---

h3. LION Interface

Displayed only on LION-enabled hardware.

*Summary:*

* Configure LION I/O module mapping

* Set channel behavior and special hardware options

*Details:*

** LION Enabled  

Toggles feature availability.  

** Channel Configuration  

Defines input/output type, pull-ups, PWM capabilities.  

** Hardware Extensions  

Depending on the LION model.  

---

h3. IoT HUB (BETA)

Experimental cloud communication layer.

*Summary:*

* Connect device to an IoT gateway (MQTT/HTTPS depending on platform)

*Details:*

** IoT Backend URL  

Cloud endpoint.  

** Device Token  

Authentication for cloud use.  

** Sync Settings  

What data is uploaded (logs, values, events).  

---

* 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. 1. Overview

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  

---

h3. Developer's Guide

[[IDE|IDE walk through]]

[[Javascript|The DTXr Javascript guide]]

[[Blockly|Blockly tutorials]]