Both sides previous revision
Previous revision
Next revision
|
Previous revision
|
blocks:drivers:example [2018-03-07 19:51] admin [Promises] |
blocks:drivers:example [2023-06-12 11:11] (current) admin Clarified connect callback parameters |
The WOCustomDrvr.ts file demonstrates how to write a driver for a device that provides a TCP "socket" based control protocol. | The WOCustomDrvr.ts file demonstrates how to write a driver for a device that provides a TCP "socket" based control protocol. |
| |
This example driver communicates with Dataton WATCHOUT production software, controlling some basic | This example driver communicates with [[https://www.dataton.com/products/watchout|Dataton WATCHOUT]] production software, controlling some basic |
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 |
- 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://www.dataton.com/downloads/watchout|free download]], so anyone can use it to try out the driver. |
| |
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:drivers:tools|code editor]], and follow along in the code as you read this walk-through. |
===== Import Statements ===== | ===== Import Statements ===== |
| |
</code> | </code> |
| |
These other files provide definitions of system functions used to communicate with the device, such as the NetworkTCP interface imported from the "system/Network" file. You can navigate to referenced classes or files by command-clicking (Mac) or control-clicking (Windows) these items in the Atom editor. The referenced files contain the relevant declarations, and often also contain comments that further describe the referenced functions. | These other files provide definitions of system functions used to communicate with the device, such as the NetworkTCP interface imported from the "system/Network" file. You can navigate to referenced classes or files by command-clicking (Mac) or control-clicking (Windows) these items in the editor. The referenced files contain the relevant declarations, and often also contain comments that further describe the referenced functions. |
| |
Not only does this provide relevant documentation. It also provides information for the TypeScript compiler as well as for the [[blocks:drivers:tools|Atom]] editor. The Atom editor uses this information to guide you when writing code, often providing hints as you type, showing available functions, parameters, etc. If you make a mistake, this is often highlighted in red by the Atom editor and/or flagged by the TypeScript compiler. | Not only does this provide relevant documentation. It also provides information for the TypeScript compiler as well as for the [[blocks:drivers:tools|code editor]]. The code editor uses this information to guide you when writing code, often providing hints as you type, showing available functions, parameters, etc. If you make a mistake, this is often highlighted in red by the code editor and/or flagged by the TypeScript compiler. |
| |
===== Driver Class Declaration ===== | ===== Driver Class Declaration ===== |
<code> | <code> |
public constructor(private socket: NetworkTCP) { | public constructor(private socket: NetworkTCP) { |
| super(socket); |
| ... |
</code> | </code> |
| |
| |
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 ==== |
| |
</code> | </code> |
| |
Event subscriptions are similar to how //addEventListener// is used in web browsers to listen to DOM events. The 'connect' event indicates that the connection status of the socket has changed. All events are described in the Network.ts file. Jump directly to the relevant declaration by command/control-clicking a //subscribe// call. | Event subscriptions are similar to how //addEventListener// is used in web browsers to listen to DOM events. The 'connect' event indicates that the connection status of the socket has changed or failed (as indicated by the type field of the message parameter). All events are described in the Network.ts file, so always look there for full details. Jump directly to the relevant declaration by command/control-clicking a //subscribe// call. |
| |
When the subscribed-to event occurs, the function body following the //[[https://basarat.gitbooks.io/typescript/docs/arrow-functions.html|lambda]]// => operator will be invoked. Either do what needs to be done right here, if its only a line or two, or call a function defined elsewhere in the driver. | When the subscribed-to event occurs, the function body following the //[[https://basarat.gitbooks.io/typescript/docs/arrow-functions.html|lambda]]// => operator will be invoked. Either do what needs to be done right here, if its only a line or two, or call a function defined elsewhere in the driver. |
</code> | </code> |
| |
[[https://en.wikipedia.org/wiki/Regular_expression|Regular expressions]] are [[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions| directly supported]] by the scripting language. Just as strings are delimited by single or double quotes, regular expression are delimited by an opening and closing forward slash. | [[https://en.wikipedia.org/wiki/Regular_expression|Regular expressions]] are [[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions| directly supported]] by the scripting language. Just as strings are delimited by single or double quotes, regular expression are delimited by a forward slash. |
| |
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://regex101.com|this one]]. Here you can enter sample data, representative of what's sent by the device, and work on the regular expression until it does what you want. Then copy the resulting expression and paste it into the driver. | 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://regex101.com|this one]]. Here you can enter sample data, representative of what's sent by the device, and work on the regular expression until it does what you want. Then copy the resulting expression and paste it into the driver. |
===== Custom Classes ===== | ===== Custom Classes ===== |
| |
For more complex functionality, you can define your own classes inside a driver, or in a library module (a separate TypeScript file store in the //script/lib// directory. Define the class inside the driver file if it's only for use by that driver. Store more general purposes classes in the //script/lib// directory, allowing them to be used from any driver. | For more complex functionality, you can define your own classes inside a driver, or in a library module (a separate TypeScript file store in the //script/lib// directory). Define the class inside the driver file if it's only used by that driver. Store more general purposes classes in ther own files in the //script/lib// directory, allowing them to be used from multiple drivers. |
| |
<code> | <code> |