Version 1.1.0

Added PWM functions, added TCP/IP support, changed syntax to match Matlab's.

Author: Molorius

DESCRIPTION

@@ -1,11 +1,11 @@
 Name: Arduino
 Title: Arduino
-Version: 1.0.0
-Date: 2017-08-25
+Version: 1.1.0
+Date: 2017-10-01
 Author: Blake Felt, [email protected]
 Maintainer: Blake Felt, [email protected]
 Description: A class that utilizes the Firmata 
  protocol to communicate with microcontrollers.
 Depends: instrument-control (>= 0.3.0)
-Categories: serial arduino control
-Autoload: yes
+Categories: arduino
+Autoload: true

README.md

@@ -1,53 +1,79 @@
 Arduino Octave
 ==============
 A class to control an Arduino board using the Firmata protocol.
-I kept most functions identical to Matlab's version for compatibility.
 
-The StandardFirmata.ino firmware needs to be loaded to your development board. 
-Serial communication is the only form possible right now.
+Note that any time a pin is specified, it must be of the form 'D#' or
+'A#'. For example, to use digital pin 11 you must type 'D11'. 
+
+The standard Firmata functionality must be uploaded to use this.
+If you're unsure what needs to be there, just upload StandardFirmata
+for serial and StandardFirmataWifi (with wifi credential set) for TCP/IP.
 
 To install, download the latest release from the release page.
-Start Octave, and move to the folder it the file is saved in.
-Type `pkg install arduino.tar.gz`
+Start Octave, and move to the folder the file is saved in.
+Type `pkg install arduino.tar.gz` into Octave's command window.
 It requires instrument-control package to run from Forge. 
-To install that, type `pkg install -forge instrument-control`
+To install that, type `pkg install -forge instrument-control`.
 
-Additional features will be added later.
-version 1.0.0
+version 1.1.0
+To do: add I2C interface
 
 Table of Contents
 =================
 * [Initialization](#initialization)
-  * [arduino](#arduinoport-board-voltage "arduino(Port, Board, Voltage)")
+  * [arduino](#arduino)
 * [General Commands](#general-commands)
-  * [configurePin](#configurepinobj-pin-mode "configurePin(obj, pin, mode)")
-  * [readDigitalPin](#readdigitalpinobj-pin "readDigitalPin(obj, pin)")
-  * [writeDigitalPin](#writedigitalpinobj-pin-val "writeDigitalPin(obj, pin, val)")
-  * [readVoltage](#readvoltageobj-pin "readVoltage(obj, pin)")
+  * [configurePin](#configurepinard-pin-mode)
+  * [readDigitalPin](#readdigitalpinard-pin)
+  * [writeDigitalPin](#writedigitalpinard-pin-val)
+  * [readVoltage](#readvoltageard-pin)
+  * [writePWMDutyCycle](#writepwmdutycycleard-pin-duty)
+  * [writePWMVoltage](#writepwmvoltageard-pin-volt)
+* [Version History](#version-history)
 
 Initialization
 ==============
 
-arduino(Port, Board, Voltage)
+arduino()
 -----------------------------
-Starts the class. All parameters are optional, the serial port should be automatically found
-(only tested on Linux). Board is to keep compatibility with Matlab and to help determine the
-maximum voltage. Voltage is a way to manually set the maximum voltage (5V on Uno, 3.3 on ESP32, etc).
-Note that Voltage is not compatible with Matlab. 
+or:
+#### arduino(port)
+#### arduino('',board)
+#### arduino(port,board)
+#### arduino(ip_address)
+#### arduino(ip_address,board)
+#### arduino(ip_address,board,tcpipport)
+#### arduino(ip_address,'',tcpipport)
+
+Open connection with a microcontroller using the Firmata protocol over serial or TCP/IP (internet).
+
+`port` - the serial port, string.
+`board` - the name of the microcontroller, string.
+`ip_address` - the ip address, string.
+`tcpipport` - the tcp/ip port, int.
 
-Returns the arduino object (used for every other function).
+If `port` is left out or an empty string, this will attempt to use the first available serial port.
+If `board` is left out or an empty string, this will try to guess the board using the pins.
+If the mapping doesn't match any known board, it will default to 'Generic 5V'.
+If `tcpipport` is left out, it will default to the Firmata default of 3030.
 
-If this is run without a parenthese (;) at the end, it will display the 
-serial port, board name (defaults to 'Uno'), all available digital and analog pins, 
-and the max voltage value being used with voltage functions.
+Note that the Firmata protocol does not specify the maximum voltage that boards read.
+If the correct voltage is not found automatically, use 'Generic 5V', 'Generic 3.3V', or 'Generic 1.8V' for `board`.
+
+Known `board` names: 'Uno', 'Nano', 'Teensy 2.0', 'Teensy 2.0 3.3V', 'MKR1000', 'ESP8266',
+'Generic 5V', 'Generic 3.3V', 'Generic 1.8V'. If an unknown board is specified,
+the voltage will default to 5V.
+
+Returns the Arduino object.
 
 General Commands
 ================
 
-configurePin(obj, pin, mode)
+configurePin(ard, pin, mode)
 ----------------------------
-If the `mode` is specified, this will set the desired pin to that mode. If not, it simply
-returns the mode already on the pin. 
+If the `mode` is specified, this will set the desired `pin` to that mode. If not, it simply
+returns the mode already on the pin. Note that this does not check that the
+pin is compatible with that mode. 
 
 |      `Mode`      |
 |------------------|
@@ -63,29 +89,72 @@ returns the mode already on the pin.
 |  'Encoder'       |
 |   'Unset'        |
 
-readDigitalPin(obj, pin)
+readDigitalPin(ard, pin)
 ------------------------
-Reads the value of a digital pin. This can also be used on analog pins.
+Reads the value of a digital `pin`. This can also be used on analog pins.
 It will automatically set the pin mode if it is not 'DigitalInput' or 'Pullup'.
 
-Returns `[val,err]` where val is 1 or 0, err is 1 if an error occured during the process. 
-Note that err is not compatible with Matlab. 
+Returns 1 if high, 0 if low.
 
-writeDigitalPin(obj, pin, val)
+writeDigitalPin(ard, pin, val)
 ------------------------------
 Writes a value to a pin. This can also be used on analog pins. 
 It will automatically set the pin mode if it is not 'DigitalOutput'.
 
-
-readVoltage(obj, pin)
+readVoltage(ard, pin)
 ---------------------
-Reads the voltage on an analog pin. It will automatically
+Reads the voltage on an analog `pin`. It will automatically
 set the pin mode if it is not 'AnalogInput'.
 
-The output value will be scaled from 0-1023 to 0-5V. Note that this is an
-approximation, and the actual maximum voltage will not be 5V without a good
-power supply.
+The output value will be scaled from 0-1023 to the estimated maximum voltage.
+The estimated max voltage is found at the start, see [above](#arduino).
+
+Returns the approximate voltage.
+
+writePWMDutyCycle(ard, pin, duty)
+---------------------------------
+Sets a PWM duty cycle for the desired `pin`. Note that this does not
+check if the pin is PWM compatible. If the pin's mode is not 'PWM', it will
+change it to that. 
+
+`duty` is a value between 0 and 1. For example, 0.25 turns on the pin for
+25% of the time.
+
+writePWMVoltage(ard, pin, volt)
+-------------------------------
+Sets a `pin` PWM duty cycle relative to the maximum voltage of the board. For example,
+if the board has a 5V max, setting `volt` to 5 will set the duty cycle to max.
+
+Trying to use a duty cycle higher than the board voltage will output the max duty.
+
+Version History
+===============
+
+Version 1.1.0
+-------------
+Tested on Octave 4.0.3, Linux kernel 3.18, Firmata 2.5.7.
+
+Added TCP/IP interface, tested with Espressif ESP8266 and Arduino MKR1000.
+
+Added 'help' features (try typing `help arduino`) for every available function. 
+
+Can now print information about the class object, such as the available pins,
+reference voltage, and the name of the sketch running on the board.
+
+Every function is now compatible with Matlab (sorry if this breaks anything).
+
+New functions:
+writePWMDutyCycle, writePWMVoltage
+
+Version 1.0.0
+-------------
+Tested on Octave 4.0.2, Linux kernel 3.18, Firmata 2.5.1. 
+
+First version. Tested with Arduino Uno, Arduino Nano, Teensy 2.0.
+
+Added serial interface. Will scan for first open port if not specified.
+
+Some optional parameters differ from Matlab's.
 
-Returns `[volt,value,err]` where volt is the approximate voltage, value is the 
-raw value (0-1023), and err is 1 if an error occured during the process.
-Note that only volt is compatible with Matlab. 
+New functions:
+arduino, configurePin, readDigitalPin, writeDigitalPin, readVoltage