mcopy/app/lib/arduino/Readme.md

Modules

lib/arduino

Constants

delay_1

2023-07-16 Clarification

Previous versions of this script intermingled and even swapped the usage of the terms 'serial' and 'device'. From here on out, the terms will be used as such:

serial - a hardware address of a serial port device - common name of a type of mcopy device (eg. camera, projector, light) that is aliased to a serial port

lib/arduino

• lib/arduino
  • ~Arduino
    • .enumerate() ⇒ Promise
    • .sendAsync(device, cmd) ⇒ Promise
    • .send(device, cmd) ⇒ Promise.<(boolean|string)>
    • .sendString(device, str) ⇒ Promise.<(boolean|string)>
    • .stateAsync()
    • .state()
    • .writeAsync(device, str) ⇒ Promise
    • .end(serial, data) ⇒ any
    • .aliasSerial(device, serial)
    • .connect(device, serial, confirm) ⇒ Promise.<string>
    • .confirmEnd(data)
    • .verify() ⇒ Promise.<boolean>
    • .distinguish() ⇒ Promise.<string>
    • .close() ⇒ Promise.<boolean>
    • .fakeConnect(serial) ⇒ Promise.<boolean>
    • .openArduino(device) ⇒ Promise
    • .closeArduino(device) ⇒ Promise

lib/arduino~Arduino

Class representing the arduino communication features.

Kind: inner class of lib/arduino

• ~Arduino
  • .enumerate() ⇒ Promise
  • .sendAsync(device, cmd) ⇒ Promise
  • .send(device, cmd) ⇒ Promise.<(boolean|string)>
  • .sendString(device, str) ⇒ Promise.<(boolean|string)>
  • .stateAsync()
  • .state()
  • .writeAsync(device, str) ⇒ Promise
  • .end(serial, data) ⇒ any
  • .aliasSerial(device, serial)
  • .connect(device, serial, confirm) ⇒ Promise.<string>
  • .confirmEnd(data)
  • .verify() ⇒ Promise.<boolean>
  • .distinguish() ⇒ Promise.<string>
  • .close() ⇒ Promise.<boolean>
  • .fakeConnect(serial) ⇒ Promise.<boolean>
  • .openArduino(device) ⇒ Promise
  • .closeArduino(device) ⇒ Promise

arduino.enumerate() ⇒ Promise

Enumerate all connected devices that might be Arduinos

Kind: instance method of Arduino
Returns: Promise - Resolves after enumerating

arduino.sendAsync(device, cmd) ⇒ Promise

Send a command to an Arduino using async/await

Kind: instance method of Arduino
Returns: Promise - Resolves after sending

Param	Type	Description
device	string	The Arduino device identifier
cmd	string	Single character command to send

arduino.send(device, cmd) ⇒ Promise.<(boolean|string)>

Sends a command to the specified Arduino and waits for a response. Handles the communication lock to prevent sending multiple commands simultaneously. Emits an 'arduino_send' event after successfully sending the command.

Kind: instance method of Arduino
Returns: Promise.<(boolean|string)> - Returns 'false' if the communication is locked, otherwise returns the response from the device.
Throws:

• Error Throws an error if the sendAsync method encounters an error.

Param	Type	Description
device	string	The Arduino device identifier.
cmd	string	The command to be sent to the Arduino.

arduino.sendString(device, str) ⇒ Promise.<(boolean|string)>

Sends a string to the specified Arduino. Handles different types of devices, including fake devices for testing purposes. Waits for a specified delay before sending the string.

Kind: instance method of Arduino
Returns: Promise.<(boolean|string)> - Returns 'true' if the string is sent successfully, otherwise returns an error message.
Throws:

• Error Throws an error if the writeAsync method encounters an error.

Param	Type	Description
device	string	The Arduino device identifier.
str	string	The string to be sent to the Arduino.

arduino.stateAsync()

Kind: instance method of Arduino

arduino.state()

Kind: instance method of Arduino

arduino.writeAsync(device, str) ⇒ Promise

Send a string to an Arduino using async/await

Kind: instance method of Arduino
Returns: Promise - Resolves after sending

Param	Type	Description
device	string	Arduino identifier
str	string	String to send

arduino.end(serial, data) ⇒ any

Handles the end of communication with the Arduino. Calculates the time taken for the communication, executes the callback, and emits an 'arduino_end' event. Handles errors and stray data received.

Kind: instance method of Arduino
Returns: any - The time taken for the communication in milliseconds.

Param	Type	Description
serial	string	The serial address of the Arduino device.
data	string	The data received from the Arduino.

arduino.aliasSerial(device, serial)

Associates an alias with an Arduinos serial address. Used to map multi-purpose devices onto the same serial connection.

Kind: instance method of Arduino

Param	Type	Description
device	string	The serial number of the target Arduino.
serial	string	The alias to be associated with the target device.

arduino.connect(device, serial, confirm) ⇒ Promise.<string>

Connects to an Arduino using its serial number. Sets up the SerialPort instance and path for the device, and handles data communication. Handles opening the connection and emitting 'arduino_end' or 'confirmEnd' events upon receiving data.

Kind: instance method of Arduino
Returns: Promise.<string> - Resolves with the device path if the connection is successful.
Throws:

• Error Rejects with an error message if the connection fails.

Param	Type	Description
device	string	The device identifier (common name).
serial	string	The serial address of the target Arduino (e.g., COM port on Windows).
confirm	function	A callback function to be executed upon receiving confirmation data.

arduino.confirmEnd(data)

Handles the confirmation data received from an Arduino. Executes the confirmation callback function if the received data is present in the list of expected values.

Kind: instance method of Arduino

Param	Type	Description
data	string	The data received from the Arduino.

arduino.verify() ⇒ Promise.<boolean>

Verifies the connection to an Arduino by sending a connect command. The confirmation callback checks if the received data matches the expected connect command.

Kind: instance method of Arduino
Returns: Promise.<boolean> - Resolves with 'true' if the connection is verified successfully.
Throws:

• Error Rejects with an error message if the connection verification fails.

arduino.distinguish() ⇒ Promise.<string>

Distinguishes the type of Arduino connected. Sends a command to the device to identify its type and resolves the promise with the received type.

Kind: instance method of Arduino
Returns: Promise.<string> - Resolves with the type of the connected Arduino-based device.
Throws:

• Error Rejects with an error message if the distinguish operation fails.

arduino.close() ⇒ Promise.<boolean>

Closes the connection to an Arduino.

Kind: instance method of Arduino
Returns: Promise.<boolean> - Resolves with 'true' if the connection is closed successfully.
Throws:

• Error Throws an error if the closeArduino method encounters an error.

arduino.fakeConnect(serial) ⇒ Promise.<boolean>

Establishes a fake connection to an Arduino for testing purposes. Creates a fake SerialPort instance with custom write and string methods.

Kind: instance method of Arduino
Returns: Promise.<boolean> - Resolves with 'true' if the fake connection is established successfully.

Param	Type	Description
serial	string	The device identifier of the fake Arduino.

arduino.openArduino(device) ⇒ Promise

Connect to an Arduino using async/await

Kind: instance method of Arduino
Returns: Promise - Resolves after opening

Param	Type	Description
device	string	Arduino identifier

arduino.closeArduino(device) ⇒ Promise

Close a connection to an Arduino using async/await

Kind: instance method of Arduino
Returns: Promise - Resolves after closing

Param	Type	Description
device	string	Arduino identifier

delay_1

2023-07-16 Clarification

Previous versions of this script intermingled and even swapped the usage of the terms 'serial' and 'device'. From here on out, the terms will be used as such:

serial - a hardware address of a serial port device - common name of a type of mcopy device (eg. camera, projector, light) that is aliased to a serial port

Kind: global constant