Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Create a read API.md page, instead of shoving it into the README.

  • Loading branch information...
commit 2b8a97f43fc8207c23a14c1be542a82558e7a748 1 parent c4f62f3
@TooTallNate authored
Showing with 162 additions and 82 deletions.
  1. +162 −0 API.md
  2. +0 −82 README.md
View
162 API.md
@@ -0,0 +1,162 @@
+# API
+
+## var mb = require('modbus-stack')
+
+The main module for `node-modbus-stack` contains the low-level StreamStack subclasses:
+`ModbusRequestStack` and `ModbusResponseStack`, as well as various contansts related to
+the protocol.
+
+### mb.FUNCTION_CODES
+
+An Object containing the defined Modbus "Function Codes", with keys in a human-readable
+format, intended to be used in place of the actual number of the function code in your code.
+
+ mb.FUNCTION_CODES.READ_COILS;
+ // returns 1
+ mb.FUNCTION_CODES.READ_INPUT_REGISTERS;
+ // returns 4
+
+### mb.EXCEPTION_CODES
+
+An Object containing the defined Modbus "Exception Codes", which are used by a Slave
+(server) in the case of an exception occuring during execution of a Function Code request.
+
+ mb.EXCEPTION_CODES.ILLEGAL_FUNCTION;
+ // returns 1
+
+
+### var req = new mb.ModbusRequestStack(stream)
+
+A `StreamStack` subclass that handles the client-side (Master) of the Modbus protocol.
+
+`ModbusRequestStack` is a low-level API for Modbus requests. It is only good for _1 single_
+request/response interaction.
+
+It's recommended to use `mbc.createClient()` for a high-level TCP-based Client API.
+
+ var socket = require('net').createConnection(502);
+ var req = new mb.ModbusRequestStack(socket);
+
+### req.request(functionCode, [arg1, arg2, arg3, ...], [callback])
+
+Invokes a Modbus request on the parent Stream. "functionCode" must be the Function Code
+that you are invoking. The (sometimes optional) "arg" arguments are specific to the
+Function Code being invoked. "callback" can be an optional callback Function to invoke
+when either an "error" or "response" occur.
+
+ req.request(mb.FUNCTION_CODES.READ_COILS, 0, 5, function(err, res) {
+ if (err) throw err;
+ console.log(res);
+ // [ true, false, true, false, true, true ]
+ });
+
+#### Event: 'response'
+
+`function(response) { }`
+
+Emitted after the response has been received and parsed. "response" is an Object
+with properties dependant on the Function Code that was invoked. In some cases,
+an Array instance is returned with the return values.
+
+#### Event: 'error'
+
+`function(error) { }`
+
+Emitted if the remote Modbus Slave responds with an Exception Code, rather than a
+successful response.
+
+### var res = new mb.ModbusResponseStack(stream)
+
+A `StreamStack` subclass that handles the server-side (Slave) of the Modbus protocol.
+
+`ModbusResponseStack` is a low-level API for handling Modbus requests and returning
+proper responses, or exceptions. It is only good for _1 single_ request/response
+interaction.
+
+It's recommended to use `mbs.createServer()` for a simpler, high-level API for writing
+a Modbus-compliant server.
+
+ require('net').createServer(function(socket) {
+ var res = new mb.ModbusResponseStack(socket);
+ }).listen(502);
+
+### res.writeResponse([arg1, arg2, ...])
+
+Writes out a Modbus response after a `request` event has been received. The arguments
+passed are dependant on the Function Code being requested. Sometimes, no arguments are
+necessary.
+
+ var results = [4, 0, 5, 10, 2];
+ res.writeResponse(results);
+
+### res.writeException(exceptionCode)
+
+Writes out a Modbus exception response after a `request` event has been received.
+"exceptionCode" must be the Exception Code you would like to return to the Master.
+
+#### Event: 'request'
+
+`function(request) { }`
+
+Emitted after a Modbus request has been received and parsed. "request" is an object
+containing:
+
+ * `functionCode` - The "Function Code" being requested.
+ * `transactionId` - The transaction ID. Usually starts at 0 and increments by 1
+ for each subsequent request on a particular socket.
+ * `protocolVersion` - The version of the Modbus protocol. This is always 0 for "Modbus/TCP".
+ * `unitIdentifier` - The unit ID. To identify which Modbus slave to talk to. This
+ is normally only used for serial-line Modbus, but can be useful
+ if implementing a TCP->Serial Modbus bridge.
+
+As well as any additional parameters relating to the Function Code being requested.
+
+
+## var mbc = require('modbus-stack/client')
+
+### mbc.createClient(port, [host])
+
+Creates and return a new `Client` instance, which is the preferred method of
+MODBUS master communication over TCP. The default MODBUS port is __502__.
+`mbc.Client` is a subclass of `net.Socket`.
+
+ var client = mbc.createClient(502, '192.168.0.1')
+
+### client.request(functionCode, [arg1, arg2, arg3, ...], [callback])
+
+Makes a MODBUS request to the remote MODBUS slave. Same as `ModusRequestStack#request()`.
+Returns a new instance of `ModbusRequestStack`.
+
+
+### mbc.REQUESTS
+
+An Object containing the individual handlers for each implemented Function Code,
+from the perspective of a Client making a Modbus request.
+
+### mbc.RESPONSES
+
+An Object containing the individual handlers for each implemented Function Code,
+from the perspective of a Client receiving the response after a request.
+
+
+## var mbs = require('modbus-stack/server')
+
+### mbs.createServer(handlers)
+
+Creates and returns a new `Server` instance, which is the preferred method of
+MODBUS Slave communication over TCP. `handlers` should be an Object with
+handlers for each individual Function Code your server will handle.
+Any Function Code requests received that doesn't have handler defined will have
+an Exception Code "Illegal Function" response. Or, `handlers` may be a single
+Function instance which is called for _all_ Function Codes. Your handler function
+should manually call `writeException()` for any Function Codes you don't care about.
+
+### mbs.REQUESTS
+
+An Object containing the individual handlers for each implemented Function Code,
+from the perspective of a Server receiving a request.
+
+### mbs.RESPONSES
+
+An Object containing the individual handlers for each implemented Function Code,
+from the perspective of a Server responding to a previous request.
View
82 README.md
@@ -78,88 +78,6 @@ rather have a single callback invoked for _all_ MODBUS requests. Just be sure to
`writeException()` manually for any "Function Codes" your server isn't going to handle.
-API
----
-
-`require('modbus-stack')`
-
- * `FUNCTION_CODES` - _Object_<br>
- Contains the defined "Function Codes" as programmer-friendly names that translate into the defined code number.<br>
- __Usage:__ `FUNCTION_CODES.READ_COILS → 1`
-
- * `EXCEPTION_CODES` - _Object_<br>
- Same as `FUNCTION_CODES`, contains the defined "Exception Codes".<br>
- __Usage:__ `EXCEPTION_CODES.ILLEGAL_FUNCTION → 1`
-
- * `ModbusRequestStack` - _Function_<br>
- A `StreamStack` subclass that handles the client-side (Master) of the MODBUS protocol.<br>
- __Usage:__ `var req = new ModbusRequestStack(stream)`
-
- * `ModbusRequestStack#request(functionCode[, param1, param2, ...], cb)` - _Function_<br>
- Writes a MODBUS request to the underlying `Stream` (usually a `net.Stream`). `response` will be
- emitted after the slave responds to the request. The first arg is the "Function Code" to request.
- Anything after that are parameters specific to each function code. `cb` is an optional callback
- to attach to the `response` and `error` events. The function should have the
- signature: `function(err, response) {}`.<br>
- __Usage:__ `req.request(FC.READ_COILS, 0, 50)`
-
- * `"response" - function(response)` - _Event_<br>
- The "response" event is fired after the remote MODBUS slave responds to the `request` previously
- sent.
-
- * `"error" - function(error)` - _Event_<br>
- The "error" event is fired if the remote MODBUS slave responds with an Exception Code instead of
- a successful response code, or if a Function Code is requested in which `node-modbus-stack` hasn't
- implemented the proper Function Code parsing logic in `client.js`.
-
- * `ModbusResponseStack` - _Function_<br>
- A `StreamStack` implementation to handle the server-side (Slave) of the MODBUS protocol.<br>
- __Usage:__ `var res = new ModbusResponseStack(stream)`
-
- * `ModbusResponseStack#writeResponse(param1[, param2, param3, ...])` - _Function_<br>
- Writes out the MODBUS response after receiving a `request` event. The parameters given are
- dependant on the MODBUS "Function Code" that was requested.<br>
- __Usage:__ `res.writeResponse(array) // After receiving a "Read Input Registers" request`
-
- * `ModbusResponseStack#writeException(exceptionCode)` - _Function_<br>
- Writes out a MODBUS exception response after receiving a `request` event. `exceptionCode`
- should be the desired exception code to respond with. See `EXCEPTION_CODES`.<br>
- __Usage:__ `res.writeException(EXCEPTION_CODES.ILLEGAL_FUNCTION)`
-
- * `"request" - function(request)` - _Event_<br>
- The "request" event is fired once a remote MODBUS master sends a Function Code request.
- `request` is an Object containing interesting properties about the request, like `functionCode`
- and any other parameters that go with the desired Function Code.
-
- * `"error" - function(error)` - _Event_<br>
- The "error" event is fired if a Function Code is requested in which `node-modbus-stack` hasn't
- implemented the proper Function Code parsing logic in `server.js`.
-
-`require('modbus-stack/client')`
-
- * `createClient(port[, host])` - _Client_<br>
- Creates and return a new `Client` instance, which is the preferred method of conventional
- MODBUS master communication over TCP. The default MODBUS port is __502__.<br>
- __Usage:__ `var client = modbusClient.createClient(502, 'example.com')`
-
- * `Client#request(functionCode[, param1, param2, ...], cb)` - _ModbusRequestStack_<br>
- Makes a MODBUS request to the remote MODBUS slave. Same as `ModusRequestStack#request()`.<br>
- __Usage:__ `var req = client.request(FC.READ_COILS, 0, 10)`
-
- * `Client#end()` - _Function_<br>
- Sends a FIN to the remote slave device, closing the TCP connection.<br>
- __Usage:__ `client.end()`
-
-`require('modbus-stack/server')`
-
- * `createServer(handlers | callback)` - _Server_<br>
- Creates and returns a new `Server` instance, which is used to make MODBUS compliant servers
- easily. `handlers` should be an Object containing keys and callbacks of the Function Codes your
- server is implementing, or a "catch-all" `callback` function can be passed to invoke for
- _every_ MODBUS request, regardless of the Function Code.<br>
- __Usage:__ `var server = modbusServer.createServer(handlers)`
-
-
[StreamStack]: http://github.com/TooTallNate/node-stream-stack
[node-serialport]: https://github.com/voodootikigod/node-serialport
[ModbusWiki]: http://en.wikipedia.org/wiki/Modbus
Please sign in to comment.
Something went wrong with that request. Please try again.