sim800l-node v0.5.0

Sim800L-node

SIM800L-node is a modern TypeScript package providing an asynchronous serial interface for SIM800L type GSM modems.

It features a SIM800L Class shielding the user from tedious AT commands configuration and management and implementing a basic FI/FO job queue; it also exposes an interface to plug your own logger in.

An object oriented SMS class provides an abstraction layer for the messaging related logic, eg : multipart formatting, PDU encoding / parsing, and Delivery reports handling.

Due to the asynchronous and unpredictable nature of UART + GSM communication, the package also make a good use of Events.

Due to recent late-night changes, the documentation needs some update, there is a brand new SMS Spooler and a kick-ass detection of rogue delivery-reports

Table of contents

• Roadmap
  • What's working atm
  • What's next
• Hardware TBD
• Installation TBD
• Usage TBD
• API
  • Summary
  • Details

Roadmap

This project is under active development, and new features will be added on the fly.

What's working atm

• Core initialization from cold boot to ready-state
• AT commands queuing and execution
• Network state monitoring and anti-brownout watchdog
• SMS jobs creation and execution

• Delivery reports

What's next

• An extensive documentation
• SMS object configuration
• Network methods (Network selection, listing, configuration...)
• SMS Inbox

Hardware

TBD

Installation

TBD

Usage

TBD

API

Summary

Exported Functions

Classes

• Sim800L
  • new Sim800L(options, simConfig)
  • instance
    • .createSms(receipient, text, [options]) ⇒ Sms
    • .initialize(callback, params) ⇒ Promise.<ModemResponse> | void
    • .checkModem(callback, params) ⇒ Promise.<ModemResponse.<CheckModemResponse>> | void
    • .checkPinRequired(callback, params) ⇒ Promise.<ModemResponse> | void
    • .unlockSim(callback, params) ⇒ Promise.<ModemResponse> | void
    • .updateCnmiConfig(callback, params) ⇒ Promise.<ModemResponse> | void
    • .resetModem(callback, params) ⇒ Promise.<ModemResponse> | void
    • .checkNetwork(callback, params) ⇒ Promise.<ModemResponse> | void
    • .activateCReg() ⇒ void
    • .execCommand(callback, params) ⇒ Promise.<ModemResponse> | void
    • .setSmsMode(callback, params) ⇒ Promise.<ModemResponse> | void
    • .close() ⇒ void
  • static
    • .list() ⇒ Array.<PortInfo>
• Sms
  • new Sms(receipient, text, [options], modem)
  • .id : string
  • .text : string
  • .status : SmsStatus
  • .send()

Details

new Sim800L(options, simConfig) Returns an object abstracting a SIM800L family serial modem.

sim800L.createSms(receipient, text, options) ⇒ Sms A function creating an Sms attached to this particular Sim800L instance

Kind: instance method of Sim800L
Returns: Sms - An instance of the Sms class

sim800L.initialize(callback, params) ⇒ Promise.<ModemResponse> | void Initialization routine for the modem. Can be called after cold-boot. The function checks if the modem is online, enables verbose mode, checks if pin is required, unlock the sim and updates the config of the modem

Kind: instance method of Sim800L
Returns: Promise.<ModemResponse> | void - A Promise resolving the ModemResponse. If a callback is provided, the function will use the callback instead and return void

sim800L.checkModem(callback, params) ⇒ Promise.<ModemResponse.<CheckModemResponse>> | void checkModem can be used to make sure the modem is in a ready state to accept AT commands

Kind: instance method of Sim800L
Returns: Promise.<ModemResponse.<CheckModemResponse>> | void - A Promise resolving the ModemResponse. If a callback is provided, the function will use the callback instead and return void

sim800L.checkPinRequired(callback, params) ⇒ Promise.<ModemResponse> | void A function used to determine the SIM current state

Kind: instance method of Sim800L
Returns: Promise.<ModemResponse> | void - A Promise resolving the ModemResponse, containing the current SimStatus. If a callback is provided, the function will use the callback instead and return void

sim800L.unlockSim(callback, params) ⇒ Promise.<ModemResponse> | void unlockSim does exactly what you think it does

Kind: instance method of Sim800L
Returns: Promise.<ModemResponse> | void - A Promise resolving the ModemResponse, containing the result. If a callback is provided, the function will use the callback instead and return void

sim800L.updateCnmiConfig(callback, params) ⇒ Promise.<ModemResponse> | void You can call updateCnmiConfig with a custom parameter to change the SMS message indications configuration

Kind: instance method of Sim800L
Returns: Promise.<ModemResponse> | void - A Promise resolving the ModemResponse, containing the result. If a callback is provided, the function will use the callback instead and return void

sim800L.resetModem(callback, params) ⇒ Promise.<ModemResponse> | void resetModem is a function that can save you from a dead-end situation, call it to soft-reset the modem, with the mode configuration you want to reset in (optional) another parameter can be pass to automatically reinitialize the modem afterwards

Kind: instance method of Sim800L
Returns: Promise.<ModemResponse> | void - A Promise resolving the ModemResponse, containing the current SimStatus. If a callback is provided, the function will use the callback instead and return void

sim800L.checkNetwork(callback, params) ⇒ Promise.<ModemResponse> | void A function that returns the current state of network connection WIP : update to return the carrier name and force connect to it if idling

Kind: instance method of Sim800L
Returns: Promise.<ModemResponse> | void - A Promise resolving the ModemResponse, containing the current network status. If a callback is provided, the function will use the callback instead and return void

sim800L.activateCReg() ⇒ void WIP

Kind: instance method of Sim800L
Returns: void - WIP

sim800L.execCommand(callback, params) ⇒ Promise.<ModemResponse> | void execCommand is the core function of the SIM800L class, it handles the AT commands, create and queue the jobs.

Each job is associated with a handler that will hold the job place in the queue until the incoming data appears satisfactory, errors, or tiemout. By default, the handler will only search for OK, ERROR, or > results, you can provide a better handling of specific commands, just remember to call job.ended = true when you want to stop hanging the queue for incoming data

Kind: instance method of Sim800L
Returns: Promise.<ModemResponse> | void - A Promise resolving the ModemResponse, containing the Response. If a callback is provided, the function will use the callback instead and return void

sim800L.setSmsMode(callback, params) ⇒ Promise.<ModemResponse> | void Sets the SMS mode (pass 0 for PDU or 1 to text mode). Please note that the Sms class currently does not support text mode, use at your own discretion

Kind: instance method of Sim800L
Returns: Promise.<ModemResponse> | void - A Promise resolving the ModemResponse, containing the result. If a callback is provided, the function will use the callback instead and return void

sim800L.close() ⇒ void Closes the current serialport communication tunnel

Kind: instance method of Sim800L
Returns: void

Sim800L.list() ⇒ Array.<PortInfo> Returns a list of available serial ports, is available statically for config purposes

Kind: static method of Sim800L
Returns: Array.<PortInfo> - An array of serial ports available

parseBuffer(buffer) ⇒ Array.<string> Parses the raw buffer input and returns a filtered array

Kind: global function
Returns: Array.<string> - A filtered array of strings representing the individual buffer lines

isOk(buffer) ⇒ boolean Parsing the buffer to tell if the command has been properly executed

Kind: global function
Returns: boolean - A boolean describing if the command has been properly executed

isWaitingForInput(parsedData) ⇒ boolean Catches the ">" character indicating that the modem waits for an input

Kind: global function
Returns: boolean - A boolean describing if the modem is waiting for an input

getError(buffer) ⇒ ModemErrorRaw

Intercepts the known error reporting patterns of the SIM800L, it also tries to get a formatted message describing the error

Kind: global function
Returns: ModemErrorRaw - The response object containing an isError boolean and the result

new Sms(receipient, text, options, modem) Creates an instance of the Sms class. the Sms is an object abstracting the logic required to handle and send SMS in PDU mode As it's designed to work with a Sim800L modem, an instance of Sim800L must be provided, you can also use the createSms() method from the Sim800L instance directly

sms.id : string

the UUID of the Sms

Kind: instance property of Sms
Read only: true

sms.text : string

the raw text of the SMS, this can be changed as long as the SMS is not in an active or sent state

Kind: instance property of Sms

sms.status : SmsStatus

An aggregated SmsStatus mimicking a single part Status even for multipart Smses

Kind: instance property of Sms
Read only: true

sms.send()

Sending the Sms (each part if multipart). uses an handler that updates the sms status property.

If using the deliveryReport property, the Sms will also listen and handle deliveryreport Events emitted by the Modem

Kind: instance method of Sms

Events

TBD

More advanced concepts

TBD

Contribution

Feel free to contribute to the project by suggesting or developing new features. Please observe these very few rules :

• Fork the project
• Create and publish a branch named wip/yourfeature
• Create a pull request on master
• Enjoy !