DTXr doc » History » Revision 83
Revision 82 (David Fredriksson, 12/09/2025 05:28 PM) → Revision 83/98 (David Fredriksson, 12/09/2025 05:30 PM)
{{>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. 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
---
h2. 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. h3. 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. h4. 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]]