Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
blocks:drivers:example [2018-03-07 19:20] admin |
blocks:drivers:example [2023-06-12 11:11] (current) admin Clarified connect callback parameters |
||
---|---|---|---|
Line 3: | Line 3: | ||
The WOCustomDrvr.ts file demonstrates how to write a driver for a device that provides a TCP " | The WOCustomDrvr.ts file demonstrates how to write a driver for a device that provides a TCP " | ||
- | This example driver communicates with Dataton WATCHOUT production software, controlling some basic | + | This example driver communicates with [[https:// |
functions. It's provided only as an example, since Blocks already has full | functions. It's provided only as an example, since Blocks already has full | ||
support for controlling WATCHOUT built-in. Using WATCHOUT as an example device | support for controlling WATCHOUT built-in. Using WATCHOUT as an example device | ||
Line 10: | Line 10: | ||
- Many of you are already familiar with WATCHOUT. | - Many of you are already familiar with WATCHOUT. | ||
- The production software UI clearly shows what's going on. | - The production software UI clearly shows what's going on. | ||
- | - It's available as a free download, so anyone can use it to try out the driver. | + | - It's available as a [[https:// |
- | + | ||
- | Open the driver using the Atom editor, and follow along in the code as you read this walk-through. | + | |
+ | Open the driver using a [[blocks: | ||
===== Import Statements ===== | ===== Import Statements ===== | ||
Line 24: | Line 23: | ||
</ | </ | ||
- | These other files provide definitions of system functions used to communicate with the device, such as the NetworkTCP interface imported from the " | + | These other files provide definitions of system functions used to communicate with the device, such as the NetworkTCP interface imported from the " |
- | Not only does this provide relevant documentation. It also provides information for the TypeScript compiler as well as for the [[blocks: | + | Not only does this provide relevant documentation. It also provides information for the TypeScript compiler as well as for the [[blocks: |
===== Driver Class Declaration ===== | ===== Driver Class Declaration ===== | ||
Line 68: | Line 67: | ||
< | < | ||
public constructor(private socket: NetworkTCP) { | public constructor(private socket: NetworkTCP) { | ||
+ | super(socket); | ||
+ | ... | ||
</ | </ | ||
Line 73: | Line 74: | ||
This parameter must be passed to the //Driver// base class using the //super// keyword, as shown. | This parameter must be passed to the //Driver// base class using the //super// keyword, as shown. | ||
- | |||
==== Event Subscriptions ==== | ==== Event Subscriptions ==== | ||
Line 84: | Line 84: | ||
</ | </ | ||
- | Event subscriptions are similar to how // | + | Event subscriptions are similar to how // |
When the subscribed-to event occurs, the function body following the // | When the subscribed-to event occurs, the function body following the // | ||
Line 204: | Line 204: | ||
- Provoke the device to send the data you're interested in. In most cases, devices only send data in response to commands. This can either be an acknowledgement of the command (or an error message if the command failed for some reason), or a reply to a question posed by the command. | - Provoke the device to send the data you're interested in. In most cases, devices only send data in response to commands. This can either be an acknowledgement of the command (or an error message if the command failed for some reason), or a reply to a question posed by the command. | ||
- Parse out the part of the data coming from the device you're interested in. | - Parse out the part of the data coming from the device you're interested in. | ||
- | - Act intelligently on the data. E.g., handle any errors, or update exposed properties according to an unexpected | + | - Act intelligently on the data. E.g., handle any errors, or update exposed properties according to a change |
For devices that communicate using a text based protocol, regular expressions often come in handy when parsing the data. | For devices that communicate using a text based protocol, regular expressions often come in handy when parsing the data. | ||
Line 212: | Line 212: | ||
</ | </ | ||
- | [[https:// | + | [[https:// |
- | While the regular expression syntax is very powerful, it is also often hard to read and understand. When developing and testing a regular expression, you may therefore want to use an online service such as [[https:// | + | While the regular expression syntax is quite powerful, it is also often hard to read and understand. When developing and testing a regular expression, you may therefore want to use an online service such as [[https:// |
- | The // | + | The // |
< | < | ||
Line 235: | Line 235: | ||
</ | </ | ||
+ | The fact that WATCHOUT allows you to tag each question, and then returns that same tag in the associated reply makes it easy to match them up. That's not always the case. Also, WATCHOUT accepts numerous commands sent back to back, possibly intermixed with questions. Many devices have limits on how fast you can send commands. Sometimes you need to wait for a command to be acknowledged by some returned data before you can send further commands. In other cases, you may have to limit how fast you send commands, and the maximum command rate may not be well documented. | ||
===== Promises ===== | ===== Promises ===== | ||
- | Communicating with a device often means doing something | + | Communicating with a device often means sending a command |
- | * Sending | + | * Asking |
- | * Initiating an action that after some pre-determined time will be followed up by some other action, such as sending | + | * Giving |
- | Since you can not (and **must not**) have your code sit tight and wait for the answer to come back, or for the time to elapse, you must instead use a [[https:// | + | Since you can not (and **must not**) have your code sit tight and wait for the answer to come back, or for the maximum |
+ | < | ||
private ask(question: | private ask(question: | ||
if (this.socket.connected) { | if (this.socket.connected) { | ||
Line 254: | Line 255: | ||
console.error(" | console.error(" | ||
} | } | ||
+ | </ | ||
- | A //promise// is an object that tracks the future outcome of the action. When this future outcome becomes clear, the promise will call a function provided by you. Alternatively, | + | A //promise// is an object that tracks the future outcome of the action. When this future outcome becomes clear, the promise will call a function provided by you. Alternatively, |
The // | The // | ||
Line 265: | Line 267: | ||
const pieces = reply.split(' | const pieces = reply.split(' | ||
if (pieces[4] === ' | if (pieces[4] === ' | ||
- | // Go through setters to notify any listeners out there | + | // Go through setters to notify any change |
this.playing = (pieces[7] === ' | this.playing = (pieces[7] === ' | ||
this.standBy = (pieces[9] === ' | this.standBy = (pieces[9] === ' | ||
Line 274: | Line 276: | ||
</ | </ | ||
- | Here you can see how the //then// function is called to pick up the outcome of the question asked. Note that the body inside the function won't be invoked until the reply comes back. | + | Here you can see how the //then// function is called to pick up the outcome of the question asked. Note that the body inside the function won't be invoked until the reply to the // |
===== Custom Classes ===== | ===== Custom Classes ===== | ||
- | For more complex functionality, | + | For more complex functionality, |
< | < |