Introduction

nec-display is amodule to control NEC large format displays over LAN-TCP or RS232-serial with JS and human friendly commands.

Main features

• different connection modes: tcp/serial/stream
• different schemas of connect-disconnect cycle
• command queuing and timing management
• events driven

Usage

const NECD = require('nec-display');

//process commands using TCP socket
const disp1 = new NECD({host: '192.168.4.207', id: 1});
disp1.emitter.on('responseFromDevice', data => console.log(data));
disp1.process('input?'); //ask for active input
/* expected response
{
  dev: 'NECDisplay',
  raw: <Buffer 01 30 30 41 44 31 32 02 30 30 30 30 36 30 30 30 30 30 38 32 30 30 30 46 03 7d 0d>,
  id: 1,
  allvalues: {
    msgtype: 'D',
    code: '0060',
    value: '000F',
    max: '0082',
    type: '00'
  },
  req: 'input',
  value: 'DPort1'
}
*/

//process commands using serial
const disp2 = new NECD({path: 'com2', id: 2});
disp2.emitter.on('responseFromDevice', data => console.log(data));
disp2.process('powercontrol on'); //power display on
/* expected response
< {
  dev: 'NECDisplay',
  raw: <Buffer 01 30 30 41 42 30 45 02 30 30 43 32 30 33 44 36 30 30 30 31 03 76 0d>,
  id: 1,
  allvalues: { msgtype: 'B', value: '0001' },
  req: 'power',
  value: 'on'
}
*/

NECD Object

The primary exported object is NECD. It extensively uses RAW object from raw-device module as its prototype. Data neccesery to process commands is in necd.xml file.

Constructor new NECD(AddressObject, OptionsObject)

• AddressObject <Object> - required. Use only properties associated with the desired mode (serial, tcp, stream)
  • name <string> - default 'NECDisplay'. The name is included in response object to easy identify a display
  • id <number|*> - default 1. NOTEs for stream mode: all displays in RS-232 chain must have unique id number. If you set id: '*' in AddressObject, all displays execute commands, but no one of them return a response. //for serial
  • path <string> - required. Use valid serial path available in system.
  • baudRate <number> - default 9600
  • dataBits <number> - default 8
  • parity <string> - default 'none'
  • stopBits <number> - default 1
    //for tcp
  • host <string> - required. Use valid IP address of display
  • port <number> - default 7142
    //for stream
  • stream <Stream> - required. The stream must be opened read/write Node stream. This mode is used when multiple displays are chained with RS232 cables and connected to single system serial port. NECD object does not care about the stream. You have to maintain stream yourself (open, close, error handling).
• OptionsObject <Object> - optional, default is {writeDuration: 500, readDuration: 500, disconnect: true}
  • writeDuration <number> - Inter-command period [ms] for set commands. A time for device to process command and to prepare and send a response.
  • readDuration <number> - Inter-command period [ms] for read commands. A time for device to prepare and send a response.
  • disconnect <boolean|number> - Connecion cycle scheme. Use true, false or timeout[ms]. True means close connection when command queue is empty, false means do not close connection, number means close connection after some ms. of connection inactivity.

Method process(...commands)

Encode and send commands to display. You can use multiple commands in single call. Commands will be queued and executed FIFO.

Regular commands

Commands are based on NEC external control protocol. Commands are strings in human friendly form command[?] [parameter].
Some examples:
powerControl off - power off the display
backlight 30 - set backlight to 30 matrixMode on - set matrix/tile mode (use of internal signal scaller)
input? - get active input
sn? - get display serial number.
Not all protocol commands are supported. All supported commands with their usage are listed in necd.xml file.
NOTE: NEC control protocol distinguishes 'parameters' and 'commands' and it is mirrored in necd.xml. From 'process' method point of view this distinction is not important.

Internal commands

There are some internal commands which start with #. They are not sent to device, but are processed by NECD object itself.

• #pause duration - Append additional pause between neighboring commands as number of miliseconds.

Event: responseFromDevice

Emited when device response is properly decoded.

• response <Object>
  • dev <string> - device name
  • raw <Buffer> - not decoded raw response
  • req <string> - request id, used to identify response value. In most cases it is just a param/command name which response is for. In some cases it is 'req' attribute for commands in 'necd.xml'
  • allvalues <Object> - some pre-decoded values, specific for NEC control protocol
  • value <string|number> - decoded response value. Return type depends on command. See necd.xml

Event: commandForDevice

Emited when command is properly encoded and sent to device. Of course only encoded property is sent to device itself.

• command <Object>
  • name <string> - device name
  • command <string> - a command itself, not parsed or encoded
  • encodedstr <string> - command encoded as string
  • encoded <Buffer> - command encoded as Buffer
  • duration <number> - time [ms] for device to process the command.

Event: connectionData

A data which comes directly from device port "as is". Not decoded, merged or chopped by splitter. Event is not emited in stream mode.

• data <Buffer>

Event: connectionStatus

Emited when device connection status changes. Event is not emited in stream mode.

• statusObj <Object>
  • dev <string> - device name
  • address <string> - device address as string
  • status <string> - connection status
  • more <string|Object> - additional status information