Vision Inspection

Installation

npm install --save @autocodingsystems/vision-inspection

Quickstart

A fully featured device implementation in 11 lines.

const server = require('net').createServer()
const device = require('@autocodingsystems/vision-inspection')(server)
device.on('connection', driver => {
    driver.on('initialise', initialise => initialise.done())
    driver.on('update', update => update.done())
    driver.on('clear', clear => clear.done())
    driver.on('resetpecblocked', reset => reset.done())
    driver.on('error', _ => {})
    driver.on('close', had_error => {})
})
server.listen(9001)

V3

const server = require('net').createServer()
const device = require('@autocodingsystems/vision-inspection')(server, 3)
device.on('connection', driver => {
    driver.on('initialise', initialise => initialise.done())
    driver.on('update', update => update.done())
    driver.on('clear', clear => clear.done())
    driver.on('datadescriptor', datadescriptor => datadescriptor.done())
    driver.on('report', report => report.done())
    driver.on('resetpecblocked', reset => reset.done())
    driver.on('error', _ => {})
    driver.on('close', had_error => {})
})
server.listen(9001)

The drivers now support v3 of the protocol which allows the device to return batch reports and events to the drivers for publication.

Where v3 differs will be marked in the documentation with a V3 tag. V3 is not a drop in replacement for V2, code written against V2 will need modification to work against V3.

V4

const server = require('net').createServer()
const device = require('@autocodingsystems/vision-inspection')(server, 4, 'C:\\temp\\devicefiles')
device.on('connection', driver => {
    driver.on('initialise', initialise => initialise.done())
    driver.on('update', update => update.done())
    driver.on('clear', clear => clear.done())
    driver.on('datadescriptor', datadescriptor => datadescriptor.done())
    driver.on('report', report => report.done())
    driver.on('resetpecblocked', reset => reset.done())
    driver.on('filetransfer', file => console.log(file.data.filepath); file.done())
    driver.on('error', _ => {})
    driver.on('close', had_error => {})
})
server.listen(9001)

API

Factory

Example

const factory = require('@autocodingsystems/vision-inspection')
const device = factory(server)

v3

const factory = require('@autocodingsystems/vision-inspection')
const device = factory(server, 3)

Description factory is the main entry point into the vision-inspection module.

Params

• server a server object created by net.createServer()

• protocol an integer requesting the protocol implementation to use. Defaults to 2, may be 2 or 3.

Returns

device object - the main interface for implementing a device.

Remarks

This function takes a tcp server object as a parameter and returns a device object.

Class: Device

Events

connection

Example

device.on('connection', driver => {})

Description

Fired when a driver connects to the device.

Data

• driver a Driver object that represents the connection to the driver.

Remarks

The underlying socket representing the connection is not available.

Methods

setFirmware

Example

device.setFirmware('Make and Model reference', 12, 4)

Description

Sets the information to identify the device to the gateway drivers. Becomes visible in the properties of the driver.

Params

• makeAndModel a string to represent the device to the drivers, can be any ascii compatible string up to 20 characters
• versionMajor the first part of the firmware version, 0-255
• versionMinor the second part of the firmware version, 0-255

Remarks

versionMajor and versionMinor are combined by the driver into a string like: 5.3. This method should be called before calling listen on the underlying server object. If this method isn't called, inbuilt generic data will be used.

Class: Driver

Events

initialise

Example

driver.on('initialise', initialise => {})

Description

Put the device into a state ready to operate. Call initialise.done() when done.

Data

• initialise.eventstates: a dictionary representing which items to initialise and how:
  • inspectionresultvalue: How to initialise the inspection system:
    • 0 - disable
    • 1 - enable
    • 2 - do not change
• initialise.done: a function to call when the device is initialised. Do not call more than once. If initialisation failed, pass an error message as the first parameter, otherwise pass nothing or a falsey value.

V3

• initialise.data.eventstates: a dictionary representing which items to initialise and how:
  • inspectionresultvalue: How to initialise the inspection system:
    • 0 - disable
    • 1 - enable
    • 2 - do not change
• initialise.data.servertime: a string representing the time on the server, for synchronisation purposes. Formatted: dd/MM/yyyy HH:mm:ss.
• initialise.done: a function to call when the device is initialised. Do not call more than once. If initialisation failed, pass an error message as the first parameter, otherwise pass nothing or a falsey value.

update

Example

driver.on('update', update => {})

Description

Start control/monitoring operations using the passed in job data.

Data

• update.params: an array of {key, value} pair objects representing the job data.
• update.done: a function to call when the update has been applied. Do not call more than once. If the update failed, pass an error message as the first parameter, otherwise pass nothing or a falsey value.

V3

• update.data.params: an array of {key, value} pair objects representing the job data.
• update.data.servertime: a string representing the time on the server, for synchronisation purposes. Formatted: dd/MM/yyyy HH:mm:ss.
• update.data.batchid: Set this to a valid batch id before calling done. See Batch Identifier Implementation for more details.
• update.done: a function to call when the update has been applied. Do not call more than once. If the update failed, pass an error message as the first parameter, otherwise pass nothing or a falsey value.

Remarks

Once update has been received, you may make goodRead, badRead, noRead and pecBlocked calls on the driver.

clear

Example

driver.on('clear', clear => {})

Description

Stop control/monitoring operations.

Data

• clear.done: a function to call when the clear has been applied. Do not call more than once. If the clear failed, pass an error message as the first parameter, otherwise pass nothing or a falsey value.

V3

• clear.data.batchid: Set this to 0 or a valid batch id before calling done.
• clear.done: a function to call when the clear has been applied. Do not call more than once. If the clear failed, pass an error message as the first parameter, otherwise pass nothing or a falsey value.

Remarks

Once clear has been received, you may no longer make goodRead, badRead, noRead and pecBlocked calls on the driver.

For correct handling of the batchid, see the protocol document Batch Identifier Implementation.

datadescriptor

V3

Example

driver.on('datadescriptor', datadescriptor => {})

Description

Tell the drivers the reporting schema we're using.

Data

• datadescriptor.data: The string representing the data descriptor to be returned to the driver, including newline characters (\n). The string is split on \n characters and trimmed to remove any leading & trailing whitespace, then recombined into a single string for sending to the drivers. The string should be ASCII compatible. See the Data Descriptor Format for more details.
• datadescriptor.done: a function to call when the datadescriptor event has been processed. Do not call more than once. If the operation failed, pass an error message as the first parameter, otherwise pass nothing or a falsey value.

Remarks

See the protocol document Data Descriptor Format for more information.

report

V3

Example

driver.on('report', report => {
    report.data.batchid = current_batchid
    report.data.parameters.push({ name: 'Parameter A', value: 37})
    report.data.parameters.push({ name: 'Parameter B', value: 24})
    report.data.events.push({ name: 'Event A', parameters: [{name: 'Event Param A', value: 38}]})
    report.done()
})

Description

This is our opportunity to send reporting data back to the drivers.

Data

• report.data: The data to report back to the drivers in a specific format. The names, values and events used should match those in the data descriptor.
• report.data.parameters: An Array of name value pairs. By default an empty array is provided so you can just push a new parameter onto it.
• report.data.events: An array of event objects. An empty array is provided, so you can just push new events onto the array.
• report.data.events[x].name: The name of the current event. From the data descriptor.
• report.data.events[x].parameters: An array of parameters associated with the event, as described in the data descriptor. Each parameter is an object with a name and value key on it.
• report.done: a function to call when the report event has been processed. Do not call more than once. If the operation failed, pass an error message as the first parameter, otherwise pass nothing or a falsey value.

Remarks

This is called periodically and is the only way we can return reporting data to the drivers - we cannot push events or value changes to the drivers as they occur, we must wait for this event.

See the protocol document Correct Batch Response Handling for more details.

error

Example

driver.on('error', error => {})

Description

Some error has occurred.

Data

• error.src: Is set to the source object of the error. This will usually be either the underlying socket or the machina finite state machine.

Remarks

Passes through errors from lower in the system.

close

Example

driver.on('close', had_error => {})

Description

The driver has disconnected

Data

• had_error: A boolean representing whether the connection was closed cleanly or whether it closed due to some error.

Remarks

Once this fires, the driver object is no longer valid and should not be used. No more data will be received or sent to the driver using this object.

Methods

goodRead

Example

device.goodRead('a barcode', 'barcodeA', '*', [
    {key: 'keyA', value: 'valueA'},
    {key: 'keyB', value: 'valueB'}
])

Description

Notifies the drivers of a good read event.

Params

• type: a string to represent the type of event that occurred. If it was a barcode read, then this would be the type of the barcode.
• info: a string to represent the actual data of the read event. If it s a barcode read, then this would be the barcode itself.
• match: a string representing the rule that was matched to say that this was a good read. Must not be empty.
• params: an array of {key, value} objects giving data about the event

Remarks

Call this after an update event whenever the program notices a good event that the driver needs to know about. The driver keeps a count of how many of these events occured during the job.

badRead

Example

device.badRead('a barcode', 'barcodeA', [
    {key: 'keyA', value: 'valueA'},
    {key: 'keyB', value: 'valueB'}
])

Description

Notifies the drivers of a bad read event.

Params

• type: a string to represent the type of event that occurred. If it was a barcode read, then this would be the type of the barcode.
• info: a string to represent the actual data of the read event. If it s a barcode read, then this would be the barcode itself.
• params: an array of {key, value} objects giving data about the event

Remarks

Call this after an update event whenever the program notices a bad event that the driver needs to know about. The driver keeps a count of how many of these events occured during the job.

noRead

Example

device.noRead([
    {key: 'keyA', value: 'valueA'},
    {key: 'keyB', value: 'valueB'}
])

Description

Notifies the drivers of a no read event.

Params

• params: an array of {key, value} objects giving data about the event

Remarks

Call this after an update event whenever the program notices a no read event that the driver needs to know about. The driver keeps a count of how many of these events occured during the job.

pecBlocked

Example

device.pecBlocked([
    {key: 'keyA', value: 'valueA'},
    {key: 'keyB', value: 'valueB'}
])

Description

Notifies the drivers of a pec blocked event.

Params

• params: an array of {key, value} objects giving data about the event

Remarks

Call this after an update event whenever the program notices a pec blocked event that the driver needs to know about. This event goes to the driver immediately and is intended to stop production immediately. Since it is a one-time event, production may continue without any remedial action - to prevent this, call the fault method.

fault

Example

device.fault('The error condition.')

Description

Set the fault status of the machine. This does not get sent down to the driver immediately but next time the drivers poll for our status.

Params

• message: a human readable string representing the cause of the fault.

Remarks

Call this any time if production should stop and be prevented from continuing until the fault conditions are rectified.

The message must be a well formatted human readable sentence that describes the current device state in a way that an end-customer can understand. It must use proper punctuation and be terminated with a full stop. Max 250 chars.

clearFault()

Example

device.clearFault()

Description

Clear the fault status of the machine.

Params

None

Remarks

Call this to allow production to continue.

This does not get sent down to the driver immediately, but next time the drivers poll for our status.

setIdleStatus()

Example

device.setIdleStatus('Arm is stowed')

Description

Set the description of the device when no job is running.

Params

• message: a human readable string representing the status.

Remarks

Represents the status of the device to the operator. This is not sent to the driver immediately but only the next time the driver polls for our status and we're not running a device (ie, update has not fired).

The message must be a well formatted human readable sentence that describes the current device state in a way that an end-customer can understand. It must use proper punctuation and be terminated with a full stop. Max 250 chars.

setRunningStatus()

Example

device.setRunningStatus('Arm is mobile')

Description

Set the description of the device when a job is running.

Params

• message: a human readable string representing the status.

Remarks

Represents the status of the device to the operator. This is not sent to the driver immediately but only the next time the driver polls for our status and we're running a device (ie, update has fired).

The message must be a well formatted human readable sentence that describes the current device state in a way that an end-customer can understand. It must use proper punctuation and be terminated with a full stop. Max 250 chars.