Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Last revision Both sides next revision | ||
blocks:drivers:concepts [2018-01-08 17:48] admin |
blocks:drivers:concepts [2024-04-16 07:10] admin USB Serial note |
||
---|---|---|---|
Line 11: | Line 11: | ||
If an adequate driver for your device already exists, using it is quite straightforward. | If an adequate driver for your device already exists, using it is quite straightforward. | ||
- | - Obtain the driver code. Drivers provided by PIXILAB may come as part of your Blocks installation, | + | - Obtain the drivers. Drivers provided by PIXILAB may come as part of your Blocks installation, |
- | - Install the driver | + | |
+ | - Install the file(s) into your Blocks server by extract the zip archive and copy all relevant files to the PIXILAB-Blocks-root/ | ||
+ | - Some rarely used device drivers are located in the driver-archive directory. If you need any of those, move those over from the archive to the acive driver directory. While blocks ignore the source code (.ts) file and use the .js it still makes sense to move/copy both the .ts and .js file to keep them in the same place. | ||
+ | - Make sure to also copy the latest version of all files in //system// and // | ||
- Restart the Block server. | - Restart the Block server. | ||
- | The driver(s) will now appear on the " | + | :!: When installing |
+ | The driver(s) will now appear on the " | ||
===== Driver Development Prerequisites ===== | ===== Driver Development Prerequisites ===== | ||
Line 38: | Line 42: | ||
* Development tools and code, as described [[blocks: | * Development tools and code, as described [[blocks: | ||
* Access to the device to be controlled, as well as all relevant documentation. | * Access to the device to be controlled, as well as all relevant documentation. | ||
- | * If the device is controlled by serial data rather than a direct network connection, you'll need a [[blocks: | + | * If the device is controlled by serial data rather than a direct network connection, you'll need either a USB-to-serial interface if you're connecting through a PIXILAB Player or a [[blocks: |
+ | |||
+ | |||
+ | ===== Anatomy of a Driver ===== | ||
+ | |||
+ | This section provides a brief overview of what's inside a driver. You may want to install the required tools, download the code and open the WOCustomDrvr.ts sample driver to follow along. After reading the brief overview below, you may also want to read the more [[blocks: | ||
+ | |||
+ | ==== Driver Class ==== | ||
+ | |||
+ | A device driver consists of a single, exported TypeScript [[https:// | ||
+ | |||
+ | < | ||
+ | @Meta.driver(' | ||
+ | export class WOCustomDrvr extends Driver< | ||
+ | </ | ||
+ | |||
+ | This class (here named // | ||
+ | |||
+ | :!: While only the .js file is required to use the driver, you typically keep the .ts " | ||
+ | |||
+ | === Constructor Function === | ||
+ | |||
+ | A new instance of the driver will be created for each device that uses the driver. This is done by calling the constructor function, passing it an object of the driven class (here NetworkTCP). The constructor takes a parameter of the type defined for the //Driver// base class (in the example above, that type is // | ||
+ | |||
+ | The constructor stores the driven instance in the private //socket// variable, allowing it to use the socket to communicate with the device via the network. See the NetworkTCP class definition for available functions used to communicate with the device. | ||
+ | |||
+ | If your device uses UDP rather than TCP (which is unusual, but not unheard of), specify the NetworkUDP class instead as the Driver type parameter and the constructor parameter. Note that the type of underlying driver also must be specified in the //driver// decorator of the class (see below). | ||
+ | |||
+ | Note that you //must// pass the underlying driver to the Driver base class using the super() call in the constructor. | ||
+ | |||
+ | ==== Decorators ==== | ||
+ | |||
+ | TypeScript | ||
+ | |||
+ | < | ||
+ | import {driver, property, callable} from " | ||
+ | </ | ||
+ | |||
+ | in which case you can use those decorators without the " | ||
+ | |||
+ | === driver === | ||
+ | This decorator, which //must// be applied to the class in order to be recognized as a valid device driver takes two parameters: | ||
+ | |||
+ | - **baseDriverType: | ||
+ | - **typeSpecificMeta: | ||
+ | |||
+ | For NetworkUDP and NetworkTCP, the only typeSpecificMeta property supported is //port//, which takes the port number to be set automatically when choosing the driver. Most devices have a fixed or default IP port number they tend to use. Specifying that port number here helps the user by setting that port number automatically when choosing the driver. | ||
+ | |||
+ | === property === | ||
+ | This decorator exposes a // | ||
+ | |||
+ | - **description?: | ||
+ | - **readOnly?: | ||
+ | |||
+ | An alternative to marking a property as read-only using the decorator is to only provide a getter. Use the decorator readOnly parameter set to true method if you want to make the property read-only from the outside, while still providing a setter for internal use. | ||
+ | |||
+ | :!: You //must// provide a setter for setting values that may change while the driver is being used, and the always set the value by assigning to the setter. Do not assign to any underlying internal value, as doing so will not update clients (e.g., panel controls) when the value changes. | ||
+ | |||
+ | === min and max === | ||
+ | Use these decorators on numeric values to specify the allowable range. This allows sliders and other controls to be properly scaled according to the allowable range. They both take a single number as parameters, specifying the desired minimum and maximum value of the property. If defined, values set (through the corresponding setter) will also be clipped to this range. | ||
+ | |||
+ | === callable === | ||
+ | |||
+ | Marks a function as accessible from Tasks. The optional parameter provides a textual description of the function. | ||
+ | |||
+ | === parameter === | ||
+ | Decorator that can be applied to parameters to // | ||
+ | ==== Learn More ==== | ||
+ | Learn more in the [[blocks: |