Project

General

Profile

DTXr doc » History » Version 89

David Fredriksson, 12/09/2025 06:01 PM

1 20 Torbjorn Carlqvist Admin
{{>toc}}
2
3
h1. DTXr documentation
4 1 Torbjorn Carlqvist Admin
5 5 Torbjorn Carlqvist Admin
h3. Installation
6 2 Torbjorn Carlqvist Admin
7 6 Torbjorn Carlqvist Admin
* System Requirements
8 74 David Fredriksson
DTXr can run on any machine that can run +Java 17+ and has sufficient with RAM and disk capacity.
9 1 Torbjorn Carlqvist Admin
10 21 Torbjorn Carlqvist Admin
|Requirement|System RAM|System DISK|Example|
11
|Minimal|512Mbyte|512Mbyte|Raspberry 1, Raspberry Zero|
12 31 Torbjorn Carlqvist Admin
|Better|512Mbyte|512Mbyte|Rasberry Zero 2|
13
|Avarage|1GByte|1Gbyte|Raspberry 2-4|
14 21 Torbjorn Carlqvist Admin
|Top|2GByte|8Gbyte|Raspberry 4, Raspberry CM4, Server, PC|
15
16 6 Torbjorn Carlqvist Admin
* Network Requirements
17
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.
18 10 Torbjorn Carlqvist Admin
19 1 Torbjorn Carlqvist Admin
* Download DTXr software packages
20 10 Torbjorn Carlqvist Admin
Currently only customers to DAVITOR can download DTXr. Contact info@davitor.com for purchase information.
21
22 15 Torbjorn Carlqvist Admin
* Install on Linux
23 60 Torbjorn Carlqvist Admin
** There is special install scripts, please follow these steps:
24 22 Torbjorn Carlqvist Admin
### Download latest DTXr _base_ image and copy to a SD-card that has 16Gbyte capacity or more
25 64 David Fredriksson
26
Or install a new image and install java
27
<pre>sudo apt install default-jdk </pre>
28
29 22 Torbjorn Carlqvist Admin
### Insert the SD card, attach keyboard and screen via cable and start the device
30 41 David Fredriksson
### When you get prompt login as **admin/davitor**
31 72 Torbjorn Carlqvist Admin
### Download the installation script from davitor repository 
32
*(note dtx.sh has an update since Jan 17th, 2024 see new parameter 'installfolder' below)*
33
*(note dtx.sh has an update since Nov 6th, 2025 see new parameter 'type' below)*
34 59 Torbjorn Carlqvist Admin
<pre>wget --user=**** --password=**** https://artifacts.davitor.com/repository/dtx-raw/scripts/dtx.sh</pre>
35 56 Torbjorn Carlqvist Admin
There is also a utillity script that can set the host name and MAC adress. Note, optional and only applicable on LION product appliances.
36 59 Torbjorn Carlqvist Admin
<pre>wget --user=**** --password=****  https://artifacts.davitor.com/repository/dtx-raw/scripts/system.sh</pre>
37 56 Torbjorn Carlqvist Admin
Make the scripts exec
38
<pre>sudo chmod 770 *.sh</pre>
39 1 Torbjorn Carlqvist Admin
### Run installation as below where you first alter:
40 72 Torbjorn Carlqvist Admin
*** 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.
41 1 Torbjorn Carlqvist Admin
*** Required version (-v x.y.z)
42 69 Torbjorn Carlqvist Admin
*** The the install folder (-f myfolder) Note: Still relative to /usr/local so (-f myfolder) results in /usr/local/myfolder/dtx...
43 57 Torbjorn Carlqvist Admin
*** Partner user name (-u ****)
44
*** Partner password (-p ****)
45
*** Application password for the HTTP interface login on port 9090 (-app-password xxxxxxx)
46 58 Torbjorn Carlqvist Admin
*** BACnet Decvice Id (bac-device-id=nnnnn)
47 57 Torbjorn Carlqvist Admin
*** BACnet password which you will use to control the BACnet device DCC (bacnet-password=xxxxxx)
48 67 Torbjorn Carlqvist Admin
*** BACnet Device Name (bac-device-name=yyyy)
49 1 Torbjorn Carlqvist Admin
*** 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.
50
*** Hardware Platform Type (platform=xx) is used to control and switch on/off special features that is hardware dependent.
51
For LION products use:
52 73 David Fredriksson
<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>
53 71 David Fredriksson
For other installations like PC, Servers etc. use:
54 72 Torbjorn Carlqvist Admin
<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>
55 1 Torbjorn Carlqvist Admin
### Utillity script to set MAC and host name
56 54 Torbjorn Carlqvist Admin
<pre>sudo ./system.sh -mac 70:B3:D5:16:E8:99 -hn DTX-L1-8R8DI</pre>
57 62 Torbjorn Carlqvist Admin
* Upgrade on linux
58 69 Torbjorn Carlqvist Admin
If you already have DTX installed and should upgrade to a new version *(Don't forget to set correct installfolder with -f)*
59 72 Torbjorn Carlqvist Admin
<pre>sudo ./dtx.sh -t scriptengine|polyglot -v 3.1.23 -f myfolder -u **** -p ****</pre>
60 69 Torbjorn Carlqvist Admin
* 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.)*
61 70 Torbjorn Carlqvist Admin
Stop<pre>sudo systemctl stop dtx_{myfolder}</pre> 
62
Start<pre>sudo systemctl start dtx_{myfolder}</pre>
63
Check status<pre>systemctl status dtx_{myfolder}</pre>
64
Disable service, wont start at reboot<pre>sudo systemctl disable dtx_{myfolder}</pre>
65
Enable service, will start automatically at reboot<pre>sudo systemctl enable dtx_{myfolder}</pre>
66 15 Torbjorn Carlqvist Admin
67 55 Torbjorn Carlqvist Admin
* For other Linux distributions follow this steps
68 15 Torbjorn Carlqvist Admin
### _TBD..._
69
70 1 Torbjorn Carlqvist Admin
* Install on Windows
71
** Follow these steps:
72 32 David Fredriksson
### _TBD..._
73 38 Torbjorn Carlqvist Admin
74 32 David Fredriksson
h3. LION Fieldbus
75 38 Torbjorn Carlqvist Admin
76 15 Torbjorn Carlqvist Admin
* See LION [[LION:Wiki]] for howto in installataion, channel assigmnets and testing.
77 1 Torbjorn Carlqvist Admin
78
79
80 78 David Fredriksson
---
81 88 David Fredriksson
h1. User's Guide
82 1 Torbjorn Carlqvist Admin
83 88 David Fredriksson
h2. DTXr Web Interface – End User Documentation
84
85 84 David Fredriksson
h2. 1. Overview
86 86 David Fredriksson
87
h4. The DTXr web interface allows users to:
88 79 David Fredriksson
* View BACnet objects and their properties
89
* Modify writable properties (e.g., Present Value)
90
* Edit weekly schedules
91
* Switch between local and remote devices
92
* Monitor alarms, events, and notifications
93
* Use real-time updates through WebSocket (local device only)
94
95 88 David Fredriksson
96
*Important:*  
97
When selecting a *remote BACnet device*, the object list and notifications *do not update automatically*.  
98
You must press *@Objects → Refresh@* to reload the data.
99
100
For the *local device that hosts the web page*, all updates (property changes, events, alarms) are received *in real time*.
101
102 79 David Fredriksson
---
103
104
h3. 2. Navigation Bar
105
106
h4. 2.1 Objects Menu
107
* *Refresh* reloads all object data and events.
108
109
_Note: Refresh is required when a remote device is selected._
110
111
h4. 2.2 Devices Menu
112
* Displays local device and all discovered BACnet devices.
113
* Devices are grouped by network.
114
* Selecting a device loads its object list.
115
116
h4. 2.3 Priority Menu
117
Controls the *BACnet write priority* used when writing Present Value.
118
119
Examples:
120
* Priority 1 – Manual Life Safety
121
* Priority 8 – Default
122
* Priority 16 – Lowest
123
124
h4. 2.4 Notifications Menu
125
Shows:
126
* Alarms
127
* Events
128
* Return-to-normal
129
130
The menu uses badge counters:
131
* Yellow = events  
132
* Red = alarms  
133
* Green = normal transitions  
134
135
---
136
137 84 David Fredriksson
h3. 3. Objects View
138 79 David Fredriksson
139
The main view lists all BACnet objects.
140
141
Features:
142
* Collapsible categories (accordions)
143
* Lazy loading of properties when expanded
144
* Editable Present Value fields where supported
145
* Real-time updates on the *local* device
146
* Manual refresh required for *remote* devices
147
148
h4. 3.1 Expanding an Object
149
Expanding an object loads:
150
* Properties
151
* Values
152
* Writable fields
153
* Schedule editor button (if applicable)
154
155
h4. 3.2 Writing Property Values
156
Steps:
157
# Edit a value in the input field.
158
# Press the Write/Save button.
159
# DTXr sends a BACnet WriteProperty with the selected priority.
160
# A popup shows success or error.
161
162
---
163
164
h3. 4. Device Discovery
165
166
h4. 4.1 Discovering Devices
167
Opening the *Devices* dropdown sends a Who-Is request and populates the list.
168
169
h4. 4.2 Selecting a Device
170
When switching devices:
171
* Properties reload
172
* Notification list reloads
173
* The selected device name appears in the navbar
174
175
h4. 4.3 Refreshing Content
176
*Mandatory* when using remote devices.
177
178
Use:
179
@Objects → Refresh@
180
181
This reloads:
182
* Object list
183
* Property values
184
* Notifications
185
186
---
187
188
h3. 5. Notifications and Events
189
190
Notifications include:
191
* Alarm
192
* Event
193
* Normal
194
195
Real-time updates:
196
* Enabled for local device
197
* Disabled for remote devices — manual refresh required
198
199
h4. 5.1 Acknowledgment
200
If a notification supports acknowledgment:
201
* Press _Acknowledge_
202
* DTXr sends BACnet AcknowledgeAlarm
203
* Notification updates when completed
204
205
---
206
207
h3. 6. Weekly Schedule Editor
208
209
h4. 6.1 Opening the Editor
210
Click the schedule property to open the weekly calendar modal.
211
212
h4. 6.2 Creating Events
213
Select a time in the calendar to create a new event.
214
215
h4. 6.3 Editing Events
216
Click an event to modify:
217
* Binary schedule → Active / Inactive
218
* Analog schedule → numeric value
219
220
h4. 6.4 Saving the Schedule
221
Click *@Save changes@* to store the weekly schedule.
222
223
The data is:
224
* Compiled into BACnet dailySchedule structures
225
* Sorted chronologically
226
* Sent to the device as JSON
227
228
---
229
230
h3. 7. Popups and Feedback
231
232
Popups indicate:
233
* Success
234
* Errors
235
* Info
236
* Warnings
237
238
---
239
240
h3. 8. Troubleshooting
241
242
h4. 8.1 Objects Not Updating
243
* Remote device selected → press Refresh  
244
* Network or device may be unreachable
245
246
h4. 8.2 Write Errors
247
Possible reasons:
248
* Incorrect priority  
249
* Object out of service  
250
* Invalid value  
251 1 Torbjorn Carlqvist Admin
252 79 David Fredriksson
h4. 8.3 Schedule Issues
253 1 Torbjorn Carlqvist Admin
* No events created  
254
* Missing object ID  
255
* Remote device requires manual refresh  
256
257
258
---
259 81 David Fredriksson
260 83 David Fredriksson
h2. Setup
261 79 David Fredriksson
262 80 David Fredriksson
DTXr is configured through the *Menu → Setup* page.  
263
All configuration settings are grouped into logical sections. Each section below provides a functional overview of what the user can configure.  
264
Values are stored in *settings.json* and applied system-wide after pressing *Save*.
265
266
*Important:*  
267
When a *remote device* is selected from the HUB interface, *a manual page refresh is required* to update configuration data.  
268
Local device information updates in real time.
269 78 David Fredriksson
h4. System
270 1 Torbjorn Carlqvist Admin
271 78 David Fredriksson
Contains all fundamental system-level access and identity configuration.
272 1 Torbjorn Carlqvist Admin
273 78 David Fredriksson
* Administrator Account  
274
  - Configure the password of the fixed “admin” user.  
275
* Operator Account  
276
  - Optional user with limited access for HMIs or machine operation.  
277
  - Username, password and start page can be assigned.  
278
* Developer Account  
279
  - Optional higher-level user with configurable module permissions  
280
    (code, objects, API, blocks, diagram, setup).  
281
* Logging  
282
  - Set the system-wide log level (Debug, Info, Warning, Error).  
283
* Hardware Platform  
284
  - Select hardware profile (PC/server, Mira/Mesh, LION, etc.).  
285
  - This controls the enable/disable state of platform-specific modules.
286
287 1 Torbjorn Carlqvist Admin
---
288 77 David Fredriksson
289 78 David Fredriksson
h4. BACnet
290 1 Torbjorn Carlqvist Admin
291 78 David Fredriksson
Defines all BACnet/IP protocol parameters for the device.
292 1 Torbjorn Carlqvist Admin
293 78 David Fredriksson
* Device Identity  
294
  - Device ID, Device Name.  
295
* Security  
296
  - BACnet password (used for Device Communication Control).  
297
* Protocol Settings  
298
  - Segmentation, Max APDU, Vendor ID and other low-level options.  
299
* Network Mode  
300
  - Basic IP communication behaviour (broadcast, BBMD usage when applicable).
301 1 Torbjorn Carlqvist Admin
302 78 David Fredriksson
This section is essential when integrating DTXr into a BACnet building automation network.
303 1 Torbjorn Carlqvist Admin
304
---
305 77 David Fredriksson
306 78 David Fredriksson
h4. Wireless Mesh
307 1 Torbjorn Carlqvist Admin
308 78 David Fredriksson
Provides access to the mesh radio configuration on supported hardware.
309 1 Torbjorn Carlqvist Admin
310 78 David Fredriksson
* Enable/Disable Mesh  
311
* Mesh Credentials  
312
  - Security keys, network key and authentication key.  
313
* Node Role  
314
  - Coordinator / Router / End Device.  
315
* Provisioning QR Code  
316
  - Device can generate a QR code containing mesh network credentials.
317 77 David Fredriksson
318 78 David Fredriksson
Note: Mesh options are disabled on platform types that do not support radio.
319 77 David Fredriksson
320
---
321
322 1 Torbjorn Carlqvist Admin
h4. Bluetooth
323 76 David Fredriksson
324 1 Torbjorn Carlqvist Admin
Configuration for onboard Bluetooth LE services (if supported by the platform).
325 76 David Fredriksson
326
* Bluetooth Console  
327 1 Torbjorn Carlqvist Admin
  - Enables BLE-based console output.  
328 76 David Fredriksson
* Beacon Mode  
329 1 Torbjorn Carlqvist Admin
  - Enables BLE advertisement and optional custom beacon name.  
330 76 David Fredriksson
* Address Visibility and Power Settings  
331
  - Controls how the device broadcasts itself to the environment.
332
333
These options are automatically enabled or disabled depending on the selected platform type.
334 1 Torbjorn Carlqvist Admin
335 76 David Fredriksson
---
336
337 1 Torbjorn Carlqvist Admin
h4. LION Interface
338 76 David Fredriksson
339
Shown only on LION-enabled platforms.
340
341
* Enable/Disable LION module support.  
342 1 Torbjorn Carlqvist Admin
* Hardware Extensions  
343 76 David Fredriksson
  - Configures behaviour of LION-specific IO hardware.  
344
* Channel Behavior  
345
  - Digital/analog features depending on LION product family.
346
347
---
348 75 David Fredriksson
349 76 David Fredriksson
h4. Davitor Advantage
350
351
Configuration for optional DAVITOR cloud lifecycle management.
352
353 75 David Fredriksson
* DRK (Davitor Reference Key)  
354 76 David Fredriksson
  - Used for remote maintenance and PLM link.  
355 75 David Fredriksson
* PLM Connectivity  
356 76 David Fredriksson
  - Service URL and communication settings when using cloud management.
357 75 David Fredriksson
358 76 David Fredriksson
---
359 75 David Fredriksson
360
h4. External Database Access
361 76 David Fredriksson
362
Lets the DTXr device communicate with an external SQL/NoSQL database.
363
364
* Connection  
365
  - Host, port and protocol information.  
366 75 David Fredriksson
* Credentials  
367 76 David Fredriksson
  - Username/password for authenticated connections.  
368
* Sync/Logging Options  
369
  - Defines how data is written externally (trend logs, events, custom data).
370
371
---
372
373 75 David Fredriksson
h4. File Integration
374 76 David Fredriksson
375
Tools for importing/exporting system content.
376
377
* Backup / Restore  
378
  - Download the current configuration or upload a saved configuration.  
379
* Project File Upload  
380 1 Torbjorn Carlqvist Admin
  - Add or replace project assets (HMIs, scripts, diagrams).  
381 76 David Fredriksson
* Logs  
382 42 David Fredriksson
  - Download generated logs for troubleshooting.
383 76 David Fredriksson
384 13 Torbjorn Carlqvist Admin
---
385 76 David Fredriksson
386
h4. HTTP Server
387 11 Torbjorn Carlqvist Admin
388 76 David Fredriksson
Controls how the embedded DTXr HTTP(S) service behaves.
389
390
* Port Configuration  
391
  - Default HTTP port is 9090.  
392
* HTTPS / TLS  
393 14 Torbjorn Carlqvist Admin
  - Optional encrypted access.  
394 76 David Fredriksson
* Session Timeout  
395
  - Auto-logout delay for inactive users.  
396 14 Torbjorn Carlqvist Admin
* Allowed Hosts  
397 11 Torbjorn Carlqvist Admin
  - Restrict network clients that can access the interface.
398 76 David Fredriksson
399 14 Torbjorn Carlqvist Admin
---
400 76 David Fredriksson
401
h4. Email
402
403
Allows the device to send or receive email for automation events.
404 11 Torbjorn Carlqvist Admin
405 76 David Fredriksson
* SMTP Server  
406 11 Torbjorn Carlqvist Admin
  - Address, port, TLS/STARTTLS.  
407 76 David Fredriksson
* Authentication  
408 14 Torbjorn Carlqvist Admin
  - Optional username/password.  
409 76 David Fredriksson
* Attachments Folder  
410
  - Path where incoming email attachments are stored.
411
412
---
413 11 Torbjorn Carlqvist Admin
414 76 David Fredriksson
h4. Location Services
415
416
The device can determine its location automatically.
417 1 Torbjorn Carlqvist Admin
418 76 David Fredriksson
* Automatic Geolocation  
419
  - Queries an external geolocation service to populate latitude/longitude.  
420
* Manual Input  
421
  - User can override location if browser access is restricted.
422
423 19 Torbjorn Carlqvist Admin
---
424 76 David Fredriksson
425 19 Torbjorn Carlqvist Admin
h4. IoT HUB (BETA)
426 76 David Fredriksson
427 1 Torbjorn Carlqvist Admin
Early-stage experimental cloud integration.
428 76 David Fredriksson
429
* Backend URL  
430 1 Torbjorn Carlqvist Admin
  - IoT gateway endpoint.  
431 76 David Fredriksson
* Device Token  
432
  - Authentication token for cloud usage.  
433 1 Torbjorn Carlqvist Admin
* Upload Options  
434 76 David Fredriksson
  - Define what data the device forwards (events, logs, telemetry).
435
436
---
437
438 1 Torbjorn Carlqvist Admin
h4. Save & Refresh
439 76 David Fredriksson
440
* Save  
441 1 Torbjorn Carlqvist Admin
  - Commits all modified settings to settings.json.  
442 76 David Fredriksson
* Refresh  
443
  - Reloads settings from device memory.  
444
  - Required after switching to a remote device.
445
446 1 Torbjorn Carlqvist Admin
447 76 David Fredriksson
---
448 1 Torbjorn Carlqvist Admin
449 83 David Fredriksson
h2. Blocks Editor (Blockly)
450 82 David Fredriksson
451
The *Blocks* page provides a visual programming environment based on Google Blockly.  
452
Users can build automation logic using drag-and-drop blocks instead of traditional code.  
453
All logic created here is converted into JavaScript and executed by the DTXr runtime.
454
455
The Blocks Editor is divided into four main areas:
456
* The *toolbox* (left side) containing categorized blocks  
457
* The *Blockly workspace* (center)  
458
* The *log and activity panels* (bottom)  
459
* Editor actions available in the top navigation bar
460
461
---
462
463
h5. Navigation Bar Features
464
465
* Blocks → *Refresh*  
466
  - Re-parses the block code displayed in the workspace.  
467
* Blocks → *Clear logs*  
468
  - Clears the log console in the footer area.  
469
* Test  
470
  - Executes the currently visible block code once, without saving.  
471
* Save  
472
  - Saves the current block workspace into the device configuration.  
473
* Activate  
474
  - Saves and also activates the block program so it runs continuously.  
475
* Notifications  
476
  - Shows system events, alarms, and normal transitions in real time.
477
478
---
479
480
h5. Blockly Workspace
481
482
The main canvas where blocks are placed and connected.
483
484
* Drag blocks from the toolbox onto the workspace.  
485
* Connect blocks to form logic chains.  
486
* Right-click a block to duplicate, delete, or collapse it.  
487
* Zoom and pan with the mouse wheel or gestures.
488
489
All changes in the workspace are local until *Save* or *Activate* is pressed.
490
491
---
492
493
h5. Toolbox Categories
494
495
The toolbox is organized into logical categories:
496
497
* JSON  
498
  - Blocks for constructing and parsing JSON objects.  
499
* Logic  
500
  - If/else, comparison, boolean operations.  
501
* Loops  
502
  - Repeat operations.  
503
* Math  
504
  - Arithmetic and numeric values.  
505
* Text  
506
  - String operations and concatenation.  
507
* Variables  
508
  - Create and manage global/local variables.  
509
510
*Events (DTX-specific)*  
511
  - Triggers for analog or binary input changes  
512
  - Astro events  
513
  - Timers  
514
  - Incoming text messages  
515
  - Diagram object push events  
516
517
*Set value / Read value (DTX BACnet extensions)*  
518
  - Write analog, binary, lighting outputs  
519
  - Read analog or binary values  
520
  - Compare input states  
521
522
*Timed tasks*  
523
  - Cron-like scheduling  
524
  - Start, cancel, pause, resume timers  
525
526
*HMI*  
527
  - Update graphical objects or maps in diagrams/HMI pages  
528
529
*Code*  
530
  - Insert raw JavaScript statements  
531
  - Create custom return statements  
532
  - Handle function call events  
533
534
*Misc*  
535
  - Print to log  
536
  - Date/time  
537
538
*Notifications*  
539
  - Send email from block logic  
540
541
These categories combine to cover automation, BACnet control, HMI interaction and notifications.
542
543
---
544
545
h5. Running and Activating Code
546
547
*Test*  
548
Executes the block logic one time, useful for debugging.
549
550
*Save*  
551
Stores the block script but does not run it automatically.
552
553
*Activate*  
554
Saves and deploys the block logic to the DTXr runtime engine.  
555
Activated logic will:
556
* Run automatically on device startup  
557
* Respond to events immediately  
558
* Allow scheduled logic to trigger without manual execution  
559
560
---
561
562
h5. Sidebars and Console
563
564
*Left Sidebar*  
565
May contain the workspace tree or additional contextual tools.
566
567
*Right Sidebar*  
568
Displays block metadata, help text or generated JavaScript depending on configuration.
569
570
*Footer Console*  
571
Two areas are available:
572
* *Log* — printed output from print blocks or runtime  
573
* *Activity* — messages about system behavior, activation, parsing, etc.
574
575
Both areas support resizing using draggable split panes.
576
577
---
578
579
h5. Working With Devices in Blocks Mode
580
581
The device selector is present but indicates:
582
583
*“Not applicable in Blocks mode”*
584
585
This is because Blockly logic always runs locally on the device that hosts DTXr.  
586
Remote devices cannot be programmed using the Blocks Editor.
587
588
---
589
590
h5. Saving Your Work
591
592
The block workspace is saved in the device’s internal configuration.  
593
A backup is included when exporting system configuration via the File Integration tools.
594
595
*Important:*  
596
If block logic interacts with remote devices (reading/writing values),  
597
use *Refresh* in Objects view to ensure the remote values have been updated recently.
598
599
---
600
601
h5. Error Handling
602
603
When errors occur:
604
* The error message appears in the log console  
605
* Pop-up notifications show parsing or execution issues  
606
* Common issues include:
607
  - Missing block connections  
608
  - Undefined variables  
609
  - Writing to unavailable BACnet objects  
610
611
---
612
613
h5. Best Practices
614
615
* Keep block structures grouped and well-organized  
616
* Name variables clearly  
617
* Use print statements during development  
618
* Test frequently before activation  
619
* Avoid long chains inside event triggers  
620
* Use timers for repeated actions, not loops
621
622
---
623
624 87 David Fredriksson
h2. BACnet
625 82 David Fredriksson
626 87 David Fredriksson
BACnet (Building Automation and Control Network) is an international open communication standard for building automation systems.  
627
It enables devices from different manufacturers to communicate, share data, and coordinate functions such as HVAC, lighting, alarms, access control and energy management.
628 76 David Fredriksson
629 87 David Fredriksson
BACnet is defined and maintained by the BACnet Committee (SSPC 135) under ASHRAE.
630
631
More information: https://bacnet.org
632
633 1 Torbjorn Carlqvist Admin
---
634
635 87 David Fredriksson
h3. Standards and Certification
636
637
BACnet is based on globally recognized standards:
638
639
* *ASHRAE Standard 135*  
640
  The core BACnet protocol specification, maintained by ASHRAE.
641
642
* *ISO 16484-5*  
643
  International standard for building automation and control networks.
644
645
* *ANSI/ASHRAE Addenda*  
646
  Regular updates ensure modern features and cyber-security enhancements.
647
648
Because BACnet is standardized internationally, devices are tested and validated against consistent technical rules.  
649
This ensures long-term compatibility and protects investments in automation systems.
650
651
---
652
653
h3. How BACnet Communication Works
654
655
BACnet defines:
656
* *Objects* — structured data models (AI, AO, BI, BO, Schedules, etc.)  
657
* *Properties* — attributes of each object (Present Value, Units, Status Flags…)  
658
* *Services* — methods for communicating (ReadProperty, WriteProperty, etc.)
659
660
Common communication mechanisms:
661
* **BACnet/IP** over UDP (default port 47808)  
662
* **Who-Is / I-Am** device discovery  
663
* **ReadProperty / WriteProperty** for data exchange  
664
* **COV (Change of Value) subscriptions** for event-driven updates  
665
* **Alarm and Event notifications**  
666
667
DTXr implements:
668
* Full BACnet/IP functionality  
669
* Device discovery  
670
* Automatic reading and writing of properties  
671
* Real-time event handling  
672
* COV subscriptions when available  
673
674
---
675
676 89 David Fredriksson
h3. Key Advantages of BACnet 
677 87 David Fredriksson
678
*Open and vendor-neutral*  
679
BACnet is not controlled by a single private company. Any manufacturer can implement the standard.  
680
This eliminates vendor lock-in and ensures long-term system freedom.
681
682
*Large global ecosystem*  
683
Hundreds of companies worldwide produce BACnet-certified devices:
684
* HVAC controllers  
685
* Sensors and actuators  
686
* Lighting systems  
687
* VAV and damper controllers  
688
* Energy monitoring systems  
689
* User interfaces and visualizations  
690
691
This means integrators can mix-and-match equipment from different brands without special gateways.
692
693
*Interoperability by design*  
694
Because BACnet defines standard object types and required properties, devices share:
695
* Common naming conventions  
696
* Common alarm/event handling behavior  
697
* Standard scheduling objects  
698
* Standard data types  
699
700
This makes exchanging live data straightforward and predictable.
701
702
*Efficient Event-Driven Communication with COV*  
703
Rather than constantly polling for updates, BACnet supports **Change of Value (COV)** subscriptions:
704
* A device notifies subscribers only when a value *actually changes*  
705
* No wasted network traffic  
706
* Faster updates for dynamic values  
707
* Lower CPU and bandwidth usage  
708
* Ideal for large systems or wireless deployments
709
710
COV is one of BACnet’s biggest advantages over legacy systems that rely on heavy cyclic polling.
711
712
*Rich Metadata Built Into the Protocol*  
713
BACnet objects include a wide range of metadata:
714
* Object Name  
715
* Description  
716
* Units  
717
* Engineering limits  
718
* Reliability state  
719
* Status flags  
720
* Priority array  
721
* Object type  
722
723
Metadata allows tools like DTXr to:
724
* Auto-discover device capabilities  
725
* Display real names and units  
726
* Visualize systems without custom drivers  
727
* Auto-generate controls and dashboards  
728
729
This reduces engineering time and improves clarity for end users.
730
731
---
732 89 David Fredriksson
h2. Davitor Advantage
733 87 David Fredriksson
h3. Interoperability and Vendor Collaboration
734
735
BACnet has a long-standing interoperability testing ecosystem:
736
737
* *BACnet Testing Laboratories (BTL)*  
738
  Certifies devices against standardized profiles, ensuring correct communication.
739
740
* *BTL Listings*  
741
  Public database of certified devices that work together reliably.
742
743
* *Plugfests*  
744
  Manufacturers meet twice per year to test their devices against each other in real networks.
745
746
The result:
747
* Multi-brand BACnet systems work reliably  
748
* Integration cost is lower  
749
* Long-term compatibility is ensured  
750
* Devices can be replaced without redesigning the entire system  
751
752
BACnet is one of the strongest and most mature interoperability ecosystems in the automation industry.
753
754
---
755
756
h3. Why BACnet Works Exceptionally Well With DTXr
757
758
DTXr is built around BACnet’s strengths:
759
* Automatic discovery of BACnet devices  
760
* Real-time event and alarm handling  
761
* Full COV support  
762
* Multi-priority writing of Present Value  
763
* Automatic metadata integration (names, units, descriptions)  
764
* Native schedule editor compatible with BACnet Schedule objects  
765
* BACnet notifications shown directly in the interface  
766
767
DTXr can be used as:
768
* A BACnet central controller  
769
* A visualization/HMI layer  
770
* A programming environment (Code + Blocks)  
771
* A diagnostics tool for technicians  
772
* A multi-device integration and commissioning tool  
773
774
DTXr leverages the power of BACnet without requiring advanced protocol knowledge from the user.
775 1 Torbjorn Carlqvist Admin
776
---
777 89 David Fredriksson
h2. DTX Overview (Development Environment)
778 1 Torbjorn Carlqvist Admin
779 89 David Fredriksson
!https://www.davitor.com/Home/DTX!
780
781
DTX (by Davitor) is a powerful development and runtime environment designed for building automation, integration, and control — especially for BACnet-based systems.  
782
The environment is directly integrated into the device, allowing engineers to create, test, and execute automation logic locally or remotely via a web browser.  
783
DTX is suitable for controllers, gateways, cloud connectors, and industrial IO devices. :contentReference[oaicite:0]{index=0}
784
785
---
786
787
h3. Core Concept: Development Inside the Device
788
789
DTX is described by Davitor as a **“Development Environment for BACnet devices”**.  
790
Its philosophy centers around **self-contained automation**, where development tools live inside the device itself — eliminating lost code, mismatched versions, or external dependencies. This enhances system integrity and long-term maintainability. :contentReference[oaicite:1]{index=1}
791
792
A major benefit of this approach:
793
* Your automation project is stored and executed natively inside the device.  
794
* You can access the development environment anywhere on the network.  
795
* No separate development workstation is required.  
796
* The same environment works on almost any hardware or operating system supporting Java 11 or higher. :contentReference[oaicite:2]{index=2}
797
798
---
799
800
h3. Key Features of DTX
801
802
*Modular and Future-Proof Design*  
803
DTX is built with modularity in mind:
804
* The development environment runs on the device.  
805
* It is platform-independent and OS-agnostic (runs wherever Java 11+ works).  
806
* It acts as a **controller**, **cloud service**, or **gateway**, depending on need. :contentReference[oaicite:3]{index=3}
807
808
*One Unified Environment*  
809
DTX includes everything needed for automation development:
810
* Full **code editor** with JavaScript (ES6) support.  
811
* A built-in **BACnet browser** for object discovery and inspection.  
812
* Easy **GUI and HMI creation** tools.  
813
* Integrated script engine, REST API bindings, email notifications, and schedule management. :contentReference[oaicite:4]{index=4}
814
815
*Use Any Developer, Any Skill Level*  
816
Since DTX uses **JavaScript**, a widely accessible language, the need for specialized proprietary system knowledge is minimized. Anyone with basic JavaScript skills can build automation logic. :contentReference[oaicite:5]{index=5}
817
818
---
819
820
h3. Protocol Integration and Interoperability
821
822
DTX natively supports protocols used in modern automation:
823
* **BACnet/IP** (full stack with browser and read/write tools)  
824
* **MODBUS** (both Master and Slave over TCP/RTU)  
825
* **REST API** (both server and client capabilities for external application integration)  
826
* Optional LION fieldbus support on specialized hardware  
827
* MQTT broker capability for IoT use cases  
828
* Serial port support (ASCII and HEX with configurable delimiter) :contentReference[oaicite:6]{index=6}
829
830
The modular approach allows data from any source (BACnet or otherwise) to be exposed directly through DTX’s REST interface — enabling integration with cloud, database or analytics platforms while preserving metadata and object structure. :contentReference[oaicite:7]{index=7}
831
832
---
833
834
h3. Unified Automation Stack
835
836
DTX unifies:
837
* Development (IDE + editor inside the device)  
838
* HMI design (visual diagram editor)  
839
* Script execution (JavaScript engine)  
840
* Protocol communication (BACnet, Modbus, HTTP, MQTT, etc.)  
841
* Notifications and email support  
842
* Database integration (built-in user database or external Postgres SQL) :contentReference[oaicite:8]{index=8}
843
844
This makes DTX not only a controller but also a **full automation ecosystem** where:
845
* Automation logic is developed, tested, and deployed locally  
846
* Values and objects are available in real time  
847
* Projects are stored in the device and cannot get disconnected from the runtime  
848
849
---
850
851
h3. Integration with Davitor Advantage
852
853
When combined with Davitor Advantage, DTX becomes a **remotely manageable node** in a scalable automation network:
854
* Develop locally on any device  
855
* Provision devices via Davitor cloud  
856
* Manage and monitor projects across multiple sites and protocols  
857
* Keep firmware, logic, and configuration synchronized across installations
858
859
See https://www.davitor.com for product details and documentation. :contentReference[oaicite:9]{index=9}
860
861
---
862
863 76 David Fredriksson
864 1 Torbjorn Carlqvist Admin
* Wireless Mesh
865 76 David Fredriksson
** _TBD..._
866 1 Torbjorn Carlqvist Admin
867 76 David Fredriksson
* Bluetooth
868 1 Torbjorn Carlqvist Admin
** _TBD..._
869 76 David Fredriksson
870
* External Database Access
871
** _TBD..._
872 1 Torbjorn Carlqvist Admin
873 76 David Fredriksson
* File Integration
874 1 Torbjorn Carlqvist Admin
** _TBD..._
875 76 David Fredriksson
876 1 Torbjorn Carlqvist Admin
* HTTP
877
** _TBD..._
878
879
* LION Interface
880
** _TBD..._
881
882
* IoT HUB (BETA)
883
** _TBD..._
884
885
886
---
887
888
889
h3. Developer's Guide
890
891
[[IDE|IDE walk through]]
892
[[Javascript|The DTXr Javascript guide]]
893
[[Blockly|Blockly tutorials]]