• Table of contents
• DTXr documentation
  • • Installation
    • LION Fieldbus
  • DTXr Web Interface – End User Documentation
  • 1. Overview
    • 2. Navigation Bar
      • 2.3 Priority MenuControls the BACnet write priority used when writing Present Value.
    • 3. Objects View
    • 4. Device Discovery
      • 4.1 Discovering DevicesOpening the Devices dropdown sends a Who-Is request and populates the list.
      • 4.3 Refreshing ContentMandatory when using remote devices.
    • 5. Notifications and Events
    • 6. Weekly Schedule Editor
      • 6.1 Opening the EditorClick the schedule property to open the weekly calendar modal.
      • 6.2 Creating EventsSelect a time in the calendar to create a new event.
      • 6.4 Saving the ScheduleClick Save changes to store the weekly schedule.
    • 7. Popups and Feedback
    • 8. Troubleshooting
  • Setup
    • • BACnet
      • Wireless Mesh
      • Bluetooth
      • LION Interface
      • Davitor Advantage
      • External Database Access
      • File Integration
      • HTTP Server
      • Email
      • Location Services
      • IoT HUB (BETA)
      • Save & Refresh
  • Blocks Editor (Blockly)
  • BACnet
    • Standards and Certification
    • How BACnet Communication Works
    • Key Advantages of BACnet (Unique Selling Points)
    • Interoperability and Vendor Collaboration
    • Why BACnet Works Exceptionally Well With DTXr
    • Developer's Guide

DTXr documentation¶

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:
    1. 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

sudo apt install default-jdk 

1. Insert the SD card, attach keyboard and screen via cable and start the device
2. When you get prompt login as admin/davitor
3. 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)
   

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

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

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

   
   Make the scripts exec
   

   sudo chmod 770 *.sh

4. 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:
  

  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"

  
  For other installations like PC, Servers etc. use:
  

  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"

1. Utillity script to set MAC and host name
   

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

• 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)
  

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

• 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

  sudo systemctl stop dtx_{myfolder}

  
  Start

  sudo systemctl start dtx_{myfolder}

  
  Check status

  systemctl status dtx_{myfolder}

  
  Disable service, wont start at reboot

  sudo systemctl disable dtx_{myfolder}

  
  Enable service, will start automatically at reboot

  sudo systemctl enable dtx_{myfolder}

• For other Linux distributions follow this steps
  1. TBD...

• Install on Windows
  • Follow these steps:
    1. TBD...

LION Fieldbus¶

• See LION Wiki for howto in installataion, channel assigmnets and testing.

---
h1. User's Guide

DTXr Web Interface – End User Documentation¶

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)

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.

---

2. Navigation Bar¶

2.1 Objects Menu

• Refresh reloads all object data and events.

Note: Refresh is required when a remote device is selected.

2.2 Devices Menu

• Displays local device and all discovered BACnet devices.
• Devices are grouped by network.
• Selecting a device loads its object list.

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

2.4 Notifications Menu
Shows:

• Alarms
• Events
• Return-to-normal

The menu uses badge counters:

• Yellow = events
• Red = alarms
• Green = normal transitions

---

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

3.1 Expanding an Object
Expanding an object loads:

• Properties
• Values
• Writable fields
• Schedule editor button (if applicable)

3.2 Writing Property Values
Steps:

1. Edit a value in the input field.
2. Press the Write/Save button.
3. DTXr sends a BACnet WriteProperty with the selected priority.
4. A popup shows success or error.

---

4. Device Discovery¶

4.1 Discovering Devices
Opening the Devices dropdown sends a Who-Is request and populates the list.¶

4.2 Selecting a Device
When switching devices:

• Properties reload
• Notification list reloads
• The selected device name appears in the navbar

4.3 Refreshing Content
Mandatory when using remote devices.¶

Use:
Objects → Refresh

This reloads:

• Object list
• Property values
• Notifications

---

5. Notifications and Events¶

Notifications include:

• Alarm
• Event
• Normal

Real-time updates:

• Enabled for local device
• Disabled for remote devices — manual refresh required

5.1 Acknowledgment
If a notification supports acknowledgment:

• Press Acknowledge
• DTXr sends BACnet AcknowledgeAlarm
• Notification updates when completed

---

6. Weekly Schedule Editor¶

6.1 Opening the Editor
Click the schedule property to open the weekly calendar modal.¶

6.2 Creating Events
Select a time in the calendar to create a new event.¶

6.3 Editing Events
Click an event to modify:

• Binary schedule → Active / Inactive
• Analog schedule → numeric value

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

---

7. Popups and Feedback¶

Popups indicate:

• Success
• Errors
• Info
• Warnings

---

8. Troubleshooting¶

8.1 Objects Not Updating

• Remote device selected → press Refresh
• Network or device may be unreachable

8.2 Write Errors
Possible reasons:

• Incorrect priority
• Object out of service
• Invalid value

8.3 Schedule Issues

• No events created
• Missing object ID
• Remote device requires manual refresh

---

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.

---

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.

---

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.

---

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.

---

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.

---

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.

---

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).

---

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.

---

HTTP Server¶

Controls how the embedded DTXr HTTP 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.

---

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.

---

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.

---

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).

---

Save & Refresh¶

• Save
  - Commits all modified settings to settings.json.
• Refresh
  - Reloads settings from device memory.
  - Required after switching to a remote device.

---

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

---

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.

---

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.

---

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.

---

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

---

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.

---

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.

---

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.

---

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

---

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¶

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

---

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.

---

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

---

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.

---

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.

---

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...

---

Developer's Guide¶

IDE walk through
The DTXr Javascript guide
Blockly tutorials