Desktop.DASH Bot Setup

September 2021

The following section outlines how to set up a "Bot" client in your Desktop.DASH V2 for use with the Telegram secure messenger service.

Home Desktop.DASH

Remotely monitor and control your Mitsubishi (FX/Alpha) or MODBUS RTU device via Desktop Dash and Telegram using your phone, tablet or PC

What is a Bot?

A Bot is a chat service app which can receive and send messages online via a messenger service - the Bot (a robot) is written in code, and in our context, we are providing Desktop.DASH with access to a Bot service account so that it can process simple messages, for example, your permitted users on Telegram may request updates and even send commands to your Desktop.DASH running app, and in this manner allow remote control of attached equipment.

So, the Bot will be controlled by Desktop.DASH (code running in the app to manage and control what the Bot does) and for your part you need to create a unique Bot account on Telegram then allow Desktop.DASH access to that account.

Creating a Bot

Let's just look at the whole process for a moment...

• You must already be a human user on Telegram before you may create a Bot (Telegram generally uses an app on your phone and your phone number as authentication, once you have created your free Telegram presence then you may choose to download the Windows/Android apps and use your PC or tablet for Bot creation/interaction later)

• Importantly, Bots cannot initiate a conversation - so you must "make the first move" to talk to your Bot, after which Desktop.DASH will register the unique chat conversation parameters and subsequently enable your Bot to talk freely with you (and others as you permit)

• To get started on Bot creation you could try this video - YouTube - Bot Creation and also Google "telegram bot setup" for inspiration

Desktop.DASH Bot Setup

Once you have your dedicated Bot created and wish to hand it over to Desktop.DASH, then from the main menu choose Admin > Options, then select the Telegram Bot tab...

Enter your Bot UserName in the box, then the Bot Token supplied in the next box. To verify the Bot's existence on the Telegram server press the [Verify Bot] button, and you should be greeted with something like the below... (JSON being JavaScript Object Notation - which is just a means to encapsulate text information in a format easy for the computer to digest).

*WARNING* Whilst the Bot UserName and Token are encrypted to disc, that doesn't preclude someone taking that file and using it in another instance of Desktop.DASH. For this reason, physical security and access control to the PC storing your project folder should also be a part of your security regime.

Meanwhile, if all is well, then let's look at the options available to help keep your Bot out of trouble!

[x] Enable Bot and allow inbound remote control commands

Select this option to even permit your Bot to poll the Telegram server over the Internet for communication requests in the very first place.

[x] Automatically connect to the server when the program starts, enters RUN Mode, etc

Select this option to permit the Bot to start working when either Desktop.DASH starts, or when the mode changes to RUN (as opposed to being in EDIT or DEMO Modes), for example, see main menu System > options...

(Note! If you do not select the Automatic Start option you can manually Start and Stop the Bot service at any time, regardless of Mode using main menu > Admin > Start IM Control and Stop IM Control menu items.)

Bot Server URL

This is currently fixed to point to the HTTPS Telegram Web Service. (Note! As Telegram is open source and may be configured to run on a local company Intranet, this option may be adapted to allow for a custom URL to be set in the future - if ever requested.)

[Bot Setup Online Help]

Opens a browser to this page.

Message LifeSpan (1 to 60 Minutes)

Every Telegram message has a TimeStamp which is UTC format (which overcomes the difficulty of managing messages from differing TimeZones).

The UTC value is in Seconds from 1st of January 1970, 00:00 Hrs in Greenwich, and is an absolute figure, currently in the order of 1.6 billion of seconds, there about's.

The purpose of using Telegram with your Bot is to provide as near as real time interaction as possible, and for this reason we can set a limit on the "age" of messages to accommodate for various circumstances. For example, you send a control message to switch an item on, and just at that instance you lose your phone signal and the message doesn't get delivered for perhaps another 20 minutes. It's probably no longer desirable that this command should be processed, so we can use the LifeSpan value to filter and drop that message.

Ideally, 1 Minute should be the longest LifeSpan value you should set.

[x] Enforce a Whitelist of permitted (comma separated) chat partners

*WARNING* It cannot be over-stressed how important this parameter is. If you do not use this option, ANYONE who can glean the name of your Bot can access it for information and worse, send remote control commands if your Desktop.DASH has any data points configured to allow remote control commands.

So, use this option, and then list the UserNames of those Chat Partners (accounts on Telegram) which are permitted to even have their request processed in the first place.

[x] Log all chats

Select this option to log to disc file all chat communications on a daily basis.

Your Telegram User Setup

In addition to the above settings, you should also ensure that each user sets their Telegram account to delete all chat content on a 24 Hour basis with your Bot.

The reason for this is that Desktop.DASH will only collect the last message sent by a user (client), and to prevent every last message from being re-processed it's unique Chat ID Sequence # is logged and checked to see if it has already been dealt with. This is a file system based approach, and so you will see a "telegram.xml" file in the project folder of your Desktop.DASH project which is used for this logging purpose.

*WARNING* Do not ever delete this file, or you could risk previously processed commands being run again. Also, do not open this file whilst Desktop.DASH is running, as file access errors may result.

Desktop.DASH Bot Commands

Note! Your incoming messages to your Bot must be from an account which has a UserName set, not just first and/or last names!

Using the same syntax as Telegram does, we have /slash commands for system information requests and our own non-slash commands as purposed by Desktop.DASH.

Once you have sent your first message to your Bot to start a conversation using the /start syntax in your Telegram client app, you will have access to the commands as follows.

(Note! You only need to initiate the Bot chat the once, ever, not every time you attempt to chat with it at any time subsequently.)

/hi

To verify your Desktop.DASH is running and your Bot is online, just send a /hi

/help

If your Bot is chatting, you will receive a greeting in return, so then try /help...

/?

Will repeat whatever previous /slash command you sent for thumb-saving convenience.

/help

Will send a listing of /slash commands that are currently available.

/status

Will send back the status of your Desktop.DASH app instance to include RUN status, Server Name, MAC Address, Local Time to verify the app instance, plus some other information.

/data

Will send back the data-log CSV file, with as much time-series data that has been accumulated for the current day in hand, if data-logging has been enabled.

/snap

Will send back a snap shot image in JPEG format of the Desktop.DASH screen in it's current Window Size at full scale. (Note! The app MUST be the top most app on your Windows desktop and not minimized or obscured by other Windows for this feature to be useful.)

*WARNING* If any other Window does obscure Desktop.DASH it will be included in the snap shot - so be aware of sensitive information that might be revealed and the risks with using this feature.

/list

Will send back a listing of available data-points that are Web-Enabled in Desktop.DASH for remote monitoring and/or control in their "Alias Name" format, for example, "IndoorAirTempC", "GarageDoorStatus".

/stores

Will send back a listing of available data-points that are Web-Enabled in Desktop.DASH for remote monitoring and/or control in their "PLC Store" format, for example "D0", "M100".

/support

Will send a link to the XML Control Website for support/contact purposes.

Query & Control Commands

To query the value of any Web-Enabled data-point you may use the "Alias" or "PLC Store" formats, and to repeat the previous query just send a ? (no slash) for thumb-saving.

For example...

To send a remote control WRITE command to a Web-Enabled data-point you may only use the "Alias" format. For example "OutsideLight on" or "OutsideLight 1" to turn a binary store on, and "OutsideLight off" or "OutsideLight 0" to turn that store off.

There is currently no repeat feature for WRITE commands (subject to future change).

Notes & Summary

The Telegram API states that their server doesn't welcome too many hits per minute - so you will see a delay in responses, currently set @ 2 Seconds, which is built into Desktop.DASH.

It is not recommended that more than 2 or 3 Chat Partners are configured per Bot server on Desktop.DASH, and ideally just the one - so as to limit Bot confusion! For example, if three Chat Partners send three simultaneous and also conflicting commands, there is no logic to control which command gets "last dibs", as the Bot will just process commands in the order they are received over the Ethernet, regardless of UTC timestamp.

The Telegram API support is a brand new feature for Desktop.DASH V2 and is subject to evolution and bug fixing.

Disclaimer

Whilst some effort has been applied to make this function robust and dependable, there are no warranties or assurances of the reliability or error free handling of this feature in Desktop.DASH, nor any guarantee that messages sent via Telegram will be correctly received and processed, there are too many variables, including the Telegram service availability, network availability and of course your configuration of the Desktop.DASH app itself, to name just a few. You should fully test out this feature and satisfy yourself of its worthiness and fitness for purpose before using in a real world situation. Please follow carefully the guidelines set out above, particularly paying attention to security features mentioned and all warnings. XML Control disclaims all liabilities. Please reflect upon the EULA in the Desktop.DASH app for more detail on limitations and your responsibilities.