Teleduino

Arduino Internet / Web Control

API (2560 full)

The sample URLs in this documentation can optionally be set to your key, which makes them relevant and functional for your device.

If you wish to set your key, enter it in the following form and click 'Set Key'.

Introduction

Sending instructions and retrieving values from your online Teleduino device is acheived by interacting with the Teleduino API.

Requests can be submitted to the API using either GET or POST, and the returned result can be in either JSON (default), JSONP or serialised PHP.

For the examples provided in this document, the GET method will be used.

Request URL

The request URL will depend on which proxy server your device is connected to.

For the examples provided in this document, the request URL will be https://us01.proxy.teleduino.org/api/1.0/2560.php.

Returned Data Packet

All returned data packets consist of three parameters at the top level. They are:

Parameter Datatype Description
status Integer The status code of the API response. These are matched as close as possible to HTTP status codes.
message Text A simple message explaining the status code.
response Array The resulting data packet response from the Teleduino.

When a response is received back from the device (status = 200), the response array will consist of three parameters. They are:

Parameter Datatype Description
result Integer Whether or not the request was successful. Possible values are 1 or 0.
time Float The time (in seconds) that the request took to complete.
values Array The returned value(s). Will remain as an empty array if no values are returned.

Analog Pin Addressing

The analog pins on the Arduino can also be used as digital pins. To keep things simple when using the Teleduino, the analog pin numbering is different to the native Arduino.

The following table shows the pin value to be used for addressing the analog pins:

Arduino Pin Teleduino Pin
A0 54
A1 55
A2 56
A3 57
A4 58
A5 59
A6 60
A7 61
A8 62
A9 63
A10 64
A11 65
A12 66
A13 67
A14 68
A15 69

Common Parameter Values

There are some parameter values that are used regardless of which method is being called.

These common parameter values are represented by a single character and are explained in the following table:

Parameter Datatype Required? Default Description
k String Yes The unique API key for the device.
r String Yes The method being requested.
o String No json The output format. Possible values are json, jsonp or php.
p String No TeleduinoReturn When the selected output format is jsonp, this sets the callback function name.
s Integer No 1 Whether or not to set the HTTP status header. Possible values are 1 or 0.

Methods

The following definitions expain in detail the methods available via the API.

Select from the list to view to a specific definition:

Wire (TWI/I2C)

reset

Resets the device.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=reset

Example Response:

Back to Methods index

getVersion

Returns the firmware version of the device.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=getVersion

Response Value Parameters:
Parameter Datatype Description
String Firmware version of the device.

Example Response:

Back to Methods index

setStatusLedPin

Sets the digital pin to be used for the status LED.

Request Parameters:
Parameter Datatype Description
pin Integer Digital pin. Possible values are 0 - 69.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=setStatusLedPin&pin=8

Example Response:

Back to Methods index

setStatusLed

Sends a flash sequence to the status LED.

Request Parameters:
Parameter Datatype Description
count Integer Flash count to be sequenced. If flash sequence time exceeds 5 seconds then timeout may occur. Possible values are 0 - 255.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=setStatusLed&count=5

Example Response:

Back to Methods index

getFreeMemory

Returns the amount of free memory available on the device.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=getFreeMemory

Response Value Parameters:
Parameter Datatype Description
Integer Free memory available, in bytes.

Example Response:

Back to Methods index

ping

Pings the device, resulting in a quick flash of the status LED.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=ping

Example Response:

Back to Methods index

getUptime

Returns the uptime of the device.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=getUptime

Response Value Parameters:
Parameter Datatype Description
Integer Uptime in milliseconds.

Example Response:

Back to Methods index

loadPresets

Loads preset values from EEPROM. This is the same as what occurs when the device starts.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=loadPresets

Example Response:

Back to Methods index

definePinMode

Sets the digital mode for a pin.

Request Parameters:
Parameter Datatype Description
pin Integer Digital pin. Possible values are 0 - 69.
mode Integer Mode. Possible values are 0 (input) or 1 (output).

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=definePinMode&pin=2&mode=1

Example Response:

Back to Methods index

setDigitalOutput

Sets the output on a digital pin.

Request Parameters:
Parameter Datatype Description
pin Integer Digital pin. Possible values are 0 - 69.
output Integer Output. Possible values are 0 (low), 1 (high) or 2 (toggle).
expire_time Integer Optional expire time (in milliseconds) for output. 0 means no expiry. Possible values are 0 - 16777215.
save Integer Optionally save the output as a preset (2560-0.1.2 and above). Can only be set if expire_time is 0. Possible values are 0 (don't save) or 1 (save).

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=setDigitalOutput&pin=2&output=2&expire_time=0&save=1

Example Response:

Back to Methods index

setPwmOutput

Sets the duty cycle of a PWM pin.

Request Parameters:
Parameter Datatype Description
pin Integer PWM pin. Possible values are 2 - 13, 44 - 46.
output Integer Output. Possible values are 0 (low) - 255 (high).

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=setPwmOutput&pin=3&output=127

Example Response:

Back to Methods index

getDigitalInput

Returns the input state of a digital pin.

Request Parameters:
Parameter Datatype Description
pin Integer Digital pin. Possible values are 0 - 69.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=getDigitalInput&pin=3

Response Value Parameters:
Parameter Datatype Description
Integer Input state of digital pin. Possible values are 0 (low) or 1 (high).

Example Response:

Back to Methods index

getAnalogInput

Returns the input value of an analog pin.

Request Parameters:
Parameter Datatype Description
pin Integer Analog pin. Possible values are 54 - 69.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=getAnalogInput&pin=14

Response Value Parameters:
Parameter Datatype Description
Integer Input value of analog pin. Possible values are 0 (low) - 1023 (high).

Example Response:

Back to Methods index

getAllInputs

Returns the input values of all the digital and analog pins.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=getAllInputs

Response Value Parameters:
Parameter Datatype Description
Integer Input values of pins.
The first 54 elements of the array are the digital inputs with possible values of 0 (low) and 1 (high).
The remainder values are the analog outputs with possible values of 0 (low) - 1023 (high).

Example Response:

Back to Methods index

setDigitalOutputs

Sets the outputs of one or more digital pins.

Request Parameters:
Parameter Datatype Description
outputs Integer An array of outputs. Possible values are 0 (low), 1 (high) or 2 (toggle).
expire_times Integer Optional array of expire times (in milliseconds) for output. 0 means no expiry. Possible values are 0 - 16777215.
offset Integer Optional array offset. Defaults to 0.
When 0: output[0] = pin 0, output[1] = pin 1
When 5: output[0] = pin 5, output[1] = pin 6
etc

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=setDigitalOutputs&outputs[0]=1&outputs[1]=1&expire_times[0]=1000&expire_times[1]=2000&offset=2

Example Response:

Back to Methods index

defineShiftRegister

Defines a cascade of up to 32 shift registers.

Request Parameters:
Parameter Datatype Description
shift_register Integer The shift register cascade we are defining. Possible values are 0 - 3.
clock_pin Integer The digital pin which is connected to the shift register clock pin. Possible values are 0 - 69.
data_pin Integer The digital pin which is connected to the shift register data pin. Possible values are 0 - 69.
latch_pin Integer The digital pin which is connected to the shift register latch pin. Possible values are 0 - 69.
enable_pin Integer Optional. The digital pin which is used to enable the shift register. Possible values are 0 - 69.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=defineShiftRegister&shift_register=0&clock_pin=3&data_pin=5&latch_pin=4

Example Response:

Back to Methods index

setShiftRegister

Sets the output values for a shift register cascade.

Request Parameters:
Parameter Datatype Description
shift_register Integer The shift register cascade we are setting. Possible values are 0 - 3.
outputs Integer An array of integers. Each element of the array represents a shift register (up to 32).
Possible values per element are 0 - 255.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=setShiftRegister&shift_register=0&outputs[0]=85&outputs[1]=170&outputs[2]=0&outputs[3]=255

Example Response:

Back to Methods index

mergeShiftRegister

Merges new output values with any existing values.

Request Parameters:
Parameter Datatype Description
shift_register Integer The shift register cascade we are setting. Possible values are 0 - 3.
action Integer Action to apply to affected outputs. Possible values are 0 (low), 1 (high) or 2 (toggle).
expire_time Integer Expire time in milliseconds. Once expired the action reverses itself. Set to 0 to never expire. Possible values are 0 - 16777215.
outputs Integer An array of integers. Each element of the array represents a shift register (up to 32).
Possible values per element are 0 - 255.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=mergeShiftRegister&shift_register=0&action=2&expire_time=1000&outputs[0]=255

Example Response:

Back to Methods index

getShiftRegister

Returns the output values for a shift register cascade.

Request Parameters:
Parameter Datatype Description
shift_register Integer The shift register cascade we are setting. Possible values are 0 - 3.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=getShiftRegister&shift_register=0

Response Value Parameters:
Parameter Datatype Description
Integer Output values of shift registers.
Each element in the array represents a shift register in the cascade (32 in total).
Possible values are 0 - 255.

Example Response:

Back to Methods index

defineSerial

Defines a serial port for use.

Request Parameters:
Parameter Datatype Description
port Integer The port we are defining. Possible values are 0 - 3.
baud Integer The baud rate of the port.
Possible values are per element are 300, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 38400,
57600 or 115200.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=defineSerial&port=0&baud=9600

Example Response:

Back to Methods index

setSerial

Write data to the serial port.

Request Parameters:
Parameter Datatype Description
port Integer The port we are writing to. Possible values are 0 - 3.
bytes Text Text to send to the serial port. Maximum length is 254 bytes.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=setSerial&port=0&bytes=Teleduino%20rocks%21%0A

Example Response:

Back to Methods index

getSerial

Read data from the serial port.

Request Parameters:
Parameter Datatype Description
port Integer The port we are reading from. Possible values are 0 - 3.
byte_count Integer Maximum number of bytes to read from the serial port. Possible values are 0 - 255.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=getSerial&port=0&byte_count=255

Response Value Parameters:
Parameter Datatype Description
Text String of bytes read from the serial port.

Example Response:

Back to Methods index

flushSerial

Flushes the serial port buffer.

Request Parameters:
Parameter Datatype Description
port Integer The port we are defining. Possible values are 0 - 3.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=flushSerial&port=0

Example Response:

Back to Methods index

defineServo

Defines the instance of a servo.

Request Parameters:
Parameter Datatype Description
servo Integer Servo instance. Possible values are 0 - 47.
pin Integer Digital pin. Possible values are 0 - 69.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=defineServo&servo=0&pin=2

Example Response:

Back to Methods index

setServo

Sets the position of a servo.

Request Parameters:
Parameter Datatype Description
servo Integer Servo instance. Possible values are 0 - 47.
position Integer Position to set the servo to. Possible values are 0 - 180.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=setServo&servo=0&position=90

Example Response:

Back to Methods index

resetEeprom

Resets the EEPROM.

Request Parameters:
Parameter Datatype Description
quarter Integer Which quarter of the EEPROM to reset. Possible values are 0 - 3.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=resetEeprom&quarter=1

Example Response:

Back to Methods index

setEeprom

Write data to the EEPROM.

Request Parameters:
Parameter Datatype Description
offset Integer Starting position of the EEPROM to write to.
bytes Text Text to write to the EEPROM. Maximum length is 253 bytes.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=setEeprom&offset=500&bytes=Teleduino%20rocks%21%0A

Example Response:

Back to Methods index

getEeprom

Read data from the EEPROM.

Request Parameters:
Parameter Datatype Description
offset Integer Starting position of the EEPROM to read from.
byte_count Integer Number of bytes to read from the EEPROM. Possible values are 0 - 255.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=getEeprom&offset=500&byte_count=17

Response Value Parameters:
Parameter Datatype Description
Text String of bytes read from the EEPROM.

Example Response:

Back to Methods index

defineWire

Starts the Wire interface.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=defineWire

Example Response:

Back to Methods index

setWire

Write data to the Wire (TWI/I2C) bus.

Request Parameters:
Parameter Datatype Description
address Integer The 7 bit address of the device to write to. Possible values are 1 - 127.
bytes Text Text to write to the Wire (TWI/I2C) bus. Maximum length is 32 bytes.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=setWire&address=1&bytes=Teleduino%20rocks%21%0A

Response Value Parameters:
Parameter Datatype Description
Integer The response from the Wire (TWI/I2C) bus.
0 - success
1 - data too long to fit in transmit buffer
2 - received NACK on transmit of address
3 - received NACK on transmit of data
4 - other error

Example Response:

Back to Methods index

getWire

Request data from the Wire (TWI/I2C) bus.

Request Parameters:
Parameter Datatype Description
address Integer The 7 bit address of the device to write to. Possible values are 1 - 127.
byte_count Integer Number of bytes being requested. Possible values are 1 - 32.

Example Request:
https://us01.proxy.teleduino.org/api/1.0/2560.php?k={KEY}&r=getWire&address=1&byte_count=32

Response Value Parameters:
Parameter Datatype Description
Text String of bytes returned from the Wire (TWI/I2C) bus.

Example Response:

Back to Methods index