This library is archived and is no longer being maintained. It can be still be downloaded and used, but is read-only and cannot be contributed to. For more information, you can view this repository on GitHub.
The Yún has two processors on board. One is an ATmega32U4 like on the Leonardo. The other is an Atheros 9331, running Linux and the OpenWRT wireless stack, which enables the board to connect to WiFi and Ethernet networks. It is possible to call programs or custom scripts on the Linux system through the Arduino to connect with various internet services. The Yún Shield shares the same architecture and features, but it is a shield and needs to be attached to a board, where the microcontroller is interfaced with the Atheros processor through hardware Serial port.
The Bridge library simplifies communication between the ATmega32U4 - or the board attached if you use the shield - and the AR9331. Bridge commands from the board microcontroller are interpreted by Python® on the AR9331. Its role is to execute programs on the GNU/Linux side when asked by Arduino, provide a shared storage space for sharing data like sensor readings between the Arduino and the Internet, and receiving commands from the Internet and passing them directly to the Arduino.
Bridge allows communication in both directions, acting as an interface to the the Linux command line. For a brief explanations of the terminal and executing commands on Linux see here.
To become familiar with the Yún family boards please see the Yún getting started page and the or the Yún Shield getting started page.
Process is used to launch processes on the Linux processor, and other things like shell scripts.
Console can be used to communicate with the network monitor in the Arduino IDE, through a shell. Functionally, it is very similar to Serial.
An interface to the Linux file system. Can be used to read/write files on the SD card, or on the USB memory if you are using the Yún Shield.
Creates a HTTP client on Linux. Acts as a wrapper for common CURL commands, by extending Process.
An asynchronous, session-less interface for communicating between Linux and Arduino.
An Arduino based HTTP client, modeled after the EthernetClient class.
An Arduino based HTTP server, modeled after the EthernetServer class.
An interface to Temboo making it easy to connect to a large variety of online tools. See the Tembo documentation for more.
Bridge is the base class for all Bridge based calls. It is not called directly, but invoked whenever you use a function that relies on it.
begin()Starts Bridge, facilitating communication between the AVR and Linux processor. This should be called once in setup()
begin() is a blocking function. Once you call Bridge.begin(), nothing else will happen in your sketch until it has completed. This process takes approximately three seconds.
1Bridge.begin()none
none
put()The put() function allows you to store data on the Linux processor using a Key/Value structure. The Key field is like a label and you can associate a value to it. The key name must be unique in order to identify the correct value. On the Linux side there is a data store where all the keys and the values are saved.
The datastore is saved in the RAM of the AR9331, you will lose the datastore when you restart the bridge software on the Linux side (through power cycling, resetting the Linux processor, or uploading a sketch through WiFi or Ethernet). You will not lose the datastore if you reset the ATMega32u4 processor.
1bridge.put(key, value)key: char or string, the key name you want to assign to identify the value.
value: char or string, the value you want to store.
None
get()get() allows you to read a key/value item previously saved on the Linux processor. You can request for a value stored in the datastore by passing get() the Key you want to search for, the support buffer, and its size. The Key is similar to a label, used to identify an associated value. The key name must be unique in order to identify the correct value.
The datastore is saved in RAM, you will lose the datastore when you restart the bridge software on the Linux side (through power cycling, resetting the Linux processor, or uploading a sketch through WiFi or Ethernet). You will not lose the datastore if you reset the ATMega32u4 processor.
1bridge.get(key, buffer, buffer_length)key: The name of the key associated with the value you are requesting.
buffer: The support buffer used to save the value returned from the searched Key. A string terminator is added after the last byte that compose the value filed has been read.
buffer_length: the length of the buffer passed to the function.
The function returns the length of the read byte of the requested value.
transfer()transfer() is used by other functions that communicate between the ATMega32u4 microcontroller and the Linux processor.
Method to transfer a frame. This methods implement a protocol that feature error correction and response from the Linux processor
The two sides of Bridge make use of a serial protocol to transfer a message to each other. A call to a Bridge.transfer(), sends a message to the Linux side and waits for an answer. transfer() also checks for the integrity of the packet and rejects packet that contain errors.
The function implements a re-transmission mechanism if an acknowledgment is not sent from Linux within 100 ms, or if the packet is corrupt. The re-transmission is repeated until an answer is received from Linux.
transfer() function returns the length of the buffer that contains the answer from Linux.
1transfer(buff1, len1, buff2, len2, buff3, len3, rxbuff, rxlen);2
3derived functions:4transfer(buff1, len1);5transfer(buff1, len1, rxBuff, rxLen);6transfer(buff1, len1, buff2, len2, rxBuff, rxLen);buff_N: is the buffer N array with the content of the message you want to send. The transfer function support up to 3 buffers to be concatenated.
len_N: is the number of element contained in the buffer_N.
rxbuff: is the support buffer that you pass as a parameter where the answer from the linux side will be stored.
rxLen: is the length of the rxBuffer.
The length of the buffer that contains the answer from Linux. In case the rxlen is shorter than the length of the answer, the function will return rxlen to indicate that the rx buffer is full.'
Process is the base class for all Bridge based calls for communicating with the Yun's shell. It is not called directly, but invoked whenever you use a function that relies on it.
begin()Starts a Linux named process. Only the command should be called here. followed by run() or runAsynchronously(), and optionally addParameter(). The named process does not start executing until run() is called.
1Process.begin(cmd)cmd (string) : the Linux command you wish to run.
none
addParameter()addParameter() adds a parameter to a Linux command initiated with begin(). It's not necessary to add spaces, addParameter() inserts them for you.
1Process.addParameter(param)param (string) : The parameter you wish to add to a command
none
run()Starts a Linux process identified in Process.begin().
run() is a blocking function. That is, once you call Process.run(), nothing else will happen in your sketch until it has completed. The time depends on the nature of the command you are executing. For a non-blocking alternative, see runAsynchronously().
1Process.run()none
int
runAsynchronously()Starts a Linux process identified in Process.begin().
Unlike run(), runAsynchronously() is not-blocking. Your sketch will continue to run while the Linux process runs in the background.
Please note that since Process.begin(). calls close the running process is terminated. This is the reason why you can not run 2 processes the same time with the same Process instance.
1Process.runAsynchronously()none
none
running()Checks a process started by runAsynchronously() to see if it is still running.
1Process.running()none
boolean
exitValue()Returns the exit value (aka return code) of a process that was running. Used by run() and runShellCommand() to return the status of the process that the user has launched.
exitValue() #### Returns a 0 if the process is has completed correctly.
If an error occurred during the process the exit value will different than 0. There isn't a standard definition for the return code, it depends on the process. Refer to the documentation of the process to know what the code means.
1Process.exitValue()none
unsigned int. 0 if the process completed correctly. Any value other than 0 means an error occurred during the process. There isn't a standard for the return code, depends on the process you have run.
close()Closes a process started by runAsynchronously().
1Process.close()none
none
runShellCommand()Starts a shell command in Linux.
runShellCommand() is a blocking function. That is, once you call Process.runShellCommand(), nothing else will happen in your sketch until it has completed. The time depends on the nature of the command you are executing. For a non-blocking alternative, see runShellCommandAsynchronously().
1Process.runShellCommand(cmd)cmd : String containing the command
int
runShellCommandAsynchronously()Starts a Linux shell command
Unlike runShellCommand(), runShellCommandAsynchronously() is not-blocking. Your sketch will continue to run while the Linux process runs in the background.
Please note that since Process.begin(). calls close the running process is terminated. This is the reason why you can not run 2 processes the same time with the same Process instance.
1Process.runShellCommandAsynchronously(cmd)cmd : String containing the command to execute
none
available()Get the number of bytes (characters) available for reading from the Linux connection. This is data that's already arrived and stored in the receive buffer. available() inherits from the Stream utility class.
1Process.available()none
the number of bytes available to read
read()Reads incoming data from a Linux process. read() inherits from the Stream utility class.
1Process.read()none
int : the first byte of incoming data available (or -1 if no data is available)
write()Writes data to a Linux process. This data is sent as a byte or series of bytes. write() inherits from the Stream utility class.
1Process.write(val)2Process.write(str)3Process.write(buf, len)val: a value to send as a single byte str: a string to send as a series of bytes buf: an array to send as a series of bytes len: the length of the buffer
byte : the number of bytes written. Reading the number is optional.
peek()Returns the next byte (character) of incoming data from a Linux process without removing it from the internal buffer. Successive calls to peek() will return the same character, as will the next call to read(). peek() inherits from the Stream utility class.
1Process.peek()none
int : the first byte of incoming data available (or -1 if no data is available)
flush()Clears the Process buffer of any bytes. Waits for the transmission of outgoing data to complete.
1Process.flush()none
none
Console is the base class for all Bridge based calls for communicating with the Yun through the serial monitor as if it were a termnal. It is not called directly, but invoked whenever you use a function that relies on it.
begin()Starts a terminal session accessible through the serial monitor.
1Console.begin()none
none
end()Ends a terminal session accessible through the serial monitor.
1Console.end()none
none
buffer()Sets the size of the buffer for the console.
1Console.buffer(size)size (int) : the size of the buffer
none
noBuffer()Removes any buffer for the console.
1Console.noBuffer()none
none
connected()Reports back the connection status of the console.
1Console.connected()none
boolean
available()Get the number of bytes (characters) available for reading from the Console. This is data that's already arrived and stored in the receive buffer. available() inherits from the Stream utility class.
1Console.available()none
the number of bytes available to read
read()Reads incoming data from the console connection. read() inherits from the Stream utility class.
1Console.read()none
int : the first byte of incoming data available (or -1 if no data is available)
write()Writes data to the console. This data is sent as a byte or series of bytes. write() inherits from the Stream utility class.
1Console.write(val)2Console.write(str)3Console.write(buf, len)val: a value to send as a single byte str: a string to send as a series of bytes buf: an array to send as a series of bytes len: the length of the buffer
byte : the number of bytes written. Reading the number is optional.
peek()Returns the next byte (character) of incoming data from the console without removing it from the internal buffer. Successive calls to peek() will return the same character, as will the next call to read(). peek() inherits from the Stream utility class.
1Console.peek()none
int : the first byte of incoming data available (or -1 if no data is available)
flush()Clears the Console buffer of any bytes. Waits for the transmission of outgoing data to complete.
1Console.flush()none
none
FileIO is the base class for writing and reading to a SD card mounted on the Yún. It is part of Bridge. It is not called directly, but invoked whenever you use a function that relies on it.
To prepare your SD card for writing and reading, create an empty folder in the SD root named "arduino". This will ensure that the Yún will create a link to the SD to the "/mnt/sd" path.
FileSystem.begin()Initializes the SD card and FileIO class. This communicates with the Linux distribution through Bridge. While functionally similar to the SD library, the underlying code and connections are different.
1FileSystem.begin()none
boolean : true on success; false on failure
FileSystem.open()Opens a file on the SD card. If the file is opened for writing, it will be created if it doesn't already exist (but the directory containing it must already exist).
This communicates with the Linux distribution through Bridge. While functionally similar to the SD library, the underlying code and connections are different.
Note: only one file can be open at a time.
1FileSystem.open(filename)2FileSystem.open(filename, mode)filename: the name the file to open, which can:include directories (delimited by forward slashes, /) - char mode (optional): the mode in which to open the file, defaults to FILE_READ. Can be either " FILE_READ: open the file for reading, starting at the beginning of the file. FILE_WRITE: open the file for reading and writing, starting at the end of the file.
a File object referring to the opened file; if the file couldn't be opened, this object will evaluate to false in a boolean context, i.e. you can test the return value with "if (f)".
FileSystem.exists()Tests whether a file or directory exists on the SD card.
This communicates with the Linux distribution through Bridge. While functionally similar to the SD library, the underlying code and hardware connections are different.
1FileSystem.exists(filename)filename: the name of the file to test for existence, which can include directories (delimited by forward-slashes, /)
boolean : true if the file or directory exists, false if not
FileSystem.mkdir()A wrapper for the mkdir command with the -p flag, FileSystem.mkdir() creates a named directory on an SD card.
This communicates with the Linux distribution through Bridge.
1FileSystem.mkdir(directory)directory: the name of the name of the directory to create. Nested directories can be created with a /.
boolean : true if the file or directory exists, false if not
FileSystem.rmdir()A wrapper for the rmdir command, FileSystem.rmdir() removes an empty directory from an SD card. Before removing a directory with a file in it, you must call FileSystem.remove().
This communicates with the Linux distribution through Bridge.
1FileSystem.rmdir(directory)directory: the name of the directory to remove.
boolean : true if successful, false if not
FileSystem.remove()A wrapper for the rm command, FileSystem.remove() removes a file or directory from an SD card.
This communicates with the Linux distribution through Bridge.
1FileSystem.remove(file)file: the name of the directory to remove.
boolean : true if successful, false if not
FileA named file to manipulate through FileIO.
This communicates with the Linux distribution through Bridge. While functionally similar to the SD library, the underlying code and connections are different.
1File filename'filename'' : the named instance of the file.
none
close()Close an open file, and ensure that any data written to it is physically saved to the SD card.
This communicates with the Linux distribution through Bridge. While functionally similar to the SD library, the underlying code and connections are different.
1'file'.close(file)file: an instance of the File class (returned by FileIO.open())
none
rewindDirectory()rewindDirectory() will bring you back to the first file in the directory on an SD card. Used in conjunction with openNextFile().
This communicates with the Linux distribution through Bridge. While functionally similar to the SD library, the underlying code and connections are different.
1file.rewindDirectory()file: an instance of the File class (returned by FileIO.open())
none
openNextFile()Reports the next file or folder in a directory.
This communicates with the Linux distribution through Bridge. While functionally similar to the SD library, the underlying code and connections are different.
1file.openNextFile()file: an instance of the File class (returned by FileIO.open())
char : the next file or folder in the path
seek()Seek to a new position in the file, which must be between 0 and the size of the file (inclusive).
This communicates with the Linux distribution through Bridge. While functionally similar to the SD library, the underlying code and connections are different.
1file.seek(pos)file: an instance of the File class (returned by FileIO.open()) pos: the position to which to seek (unsigned long)
boolean : true for success, false for failure
position()Get the current position within the file (i.e. the location to which the next byte will be read from or written to).
This communicates with the Linux distribution through Bridge. While functionally similar to the SD library, the underlying code and connections are different.
1file.position()file: an instance of the File class (returned by FileIO.open())
unsigned long :the position within the file
size()Get the size of the current file.
This communicates with the Linux distribution through Bridge. While functionally similar to the SD library, the underlying code and connections are different.
1file.size()file: an instance of the File class (returned by FileIO.open())
unsigned long : the size of the file in bytes
available()Check if there are any bytes available for reading from the file.
available() inherits from the Stream utility class.
This communicates with the Linux distribution through Bridge. While functionally similar to the SD library, the underlying code and connections are different.
1file.available()file: an instance of the File class (returned by FileIO.open())
int : the number of bytes available
read()Read a byte from the file.
read() inherits from the Stream utility class.
This communicates with the Linux distribution through Bridge. While functionally similar to the SD library, the underlying code and connections are different.
1file.read()file: an instance of the File class (returned by FileIO.open())
The next byte (or character), or -1 if none is available.
write()Write data to the file.
This communicates with the Linux distribution through Bridge. While functionally similar to the SD library, the underlying code and connections are different.
1file.write(data)2file.write(buf, len)file: an instance of the File class (returned by FileIO.open()) data: the byte, char, or string (char *) to write buf: an array of characters or bytes len: the number of elements in buf
byte : write() will return the number of bytes written, though reading that number is optional
peek()Read a byte from the file without advancing to the next one. Successive calls to peek() will return the same value, as will the next call to read().
peek() inherits from the Stream utility class.
This communicates with the Linux distribution through Bridge. While functionally similar to the SD library, the underlying code and connections are different.
1file.peek()file: an instance of the File class (returned by FileIO.open())
The next byte (or character), or -1 if none is available.
flush()flush() clears the buffer once all outgoing characters have been sent.
flush() inherits from the Stream utility class.
This communicates with the Linux distribution through Bridge. While functionally similar to the SD library, the underlying code and connections are different.
1file.flush()file: an instance of the File class (returned by FileIO.open())
none
Mailbox is the base class for all Bridge based calls that use the mailbox interface for communicating between the two processors on the Yun.
begin()Starts the mailbox on the Linux and Arduino processors.
1Mailbox.begin()none
none
end()Closes all existing mailboxes on the Linux and Arduino processors.
1Mailbox.end()none
none
readMessage()Receive a message and store it inside a String
1Mailbox.readMessage(buffer, size)buffer : String : the named buffer to store the message in size : unsigned int, max length 128 : number of bytes in the message
message from Bridge.transfer()
writeMessage()Sends a message from the 32U4 to the AR9331
1Mailbox.writeMessage(buffer, size)2Mailbox.writeMessage(content)buffer : int : the buffer to send the message to size : unsigned int, max length 128 : number of bytes in the message content : String : message to send information to.
none
writeJSON()Sends a JSON message from the 32U4 to the AR9331
1Mailbox.JSON(message)message : String : message to send information to.
none
messageAvailable()Checks and Returns the size of the next available message.
1Mailbox.messageAvailable()none
int : The size of the next available message. Returns 0 if there is no messages in the queue.
See also Bridge.transfer()
HttpClient extends Process and acts as a wrapper for common cURL commands by creating a HTTP client in the Linux side.
get()A wrapper for the cURL command get.
The method gets the specified URL from a server.
1client.get(url)client : an instance of the HttpClient class url : a string containing the url to retrieve
none
getAsynchronously()A wrapper for the cURL command get. This command runs asynchronously and is non-blocking
The method gets the specified URL from a server.
1client.getAsynchronously(url)client : an instance of the HttpClient class url : a string containing the url to retrieve
none
ready()Checks if an HTTP request initiated with getAsynchronously() is still in progress.
1client.ready()client : an instance of the HttpClient class
boolean false if the request is still in progress, true if the request is completed
getResult()Checks a process started by runAsynchronously() to see if it is still running.
1client.getResult()client : an instance of the HttpClient class
// see also exitValue()
BridgeClientBridgeClient is the base class for all client based calls on the Yún. It is not called directly, but invoked whenever you use a function that relies on it.
1BridgeClient clientclient : the named client to refer to
None
BridgeSSLClientBridgeSSLClient is the base class for all client based calls to SSL services on the Yún. It is not called directly, but invoked whenever you use a function that relies on it.
1BridgeSSLClient clientclient : the named client to refer to
None
stop()Disconnect from the server.
1client.stop()client : the named instance of YunClient
None
connect()Connects to a specified IP address and port. The return value indicates success or failure. Also supports DNS lookups when using a domain name.
1client.connect()2client.connect(ip, port)3client.connect(URL, port)client : the named instance of YunClient ip: the IP address that the client will connect to (array of 4 bytes) URL: the domain name the client will connect to (string, ex.:"arduino.cc") port: the port that the client will connect to (int)
Returns true if the connection succeeds, false if not.
connected()Whether or not the client is connected. Note that a client is considered connected if the connection has been closed but there is still unread data.
1client.connected()client : the named instance of YunClient
Returns true if the client is connected, false if not.
available()Returns the number of bytes available for reading (that is, the amount of data that has been written to the client by the server it is connected to).
available() inherits from the Stream utility class.
1client.available()client : the named instance of YunClient
The number of bytes available.
read()Read the next byte received from the server the client is connected to (after the last call to read()).
read() inherits from the Stream utility class.
1client.read()client : the named instance of YunClient
The next byte (or character), or -1 if none is available.
write()Write data to the server the client is connected to.
1client.write(data)client : the named instance of YunClient data: the byte or char to write
byte: the number of characters written. it is not necessary to read this value.
peek()Read a byte from the file without advancing to the next one. That is, successive calls to peek() will return the same value, as will the next call to read().
1client.peek()client : the named instance of YunClient
int : the first byte of incoming data available (or -1 if no data is available)
flush()Discard any bytes that have been written to the client but not yet read.
1client.flush()client : the named instance of YunClient
none
BridgeServer is the base class for all server server based calls on the Yun. It is not called directly, but invoked whenever you use a function that relies on it.
begin()Tells the server to begin listening for incoming connections. The Bridge server communicates on port 5555 at localhost.
1server.begin()server : the named instance of YunServer
None
listenOnLocalhost()Tells the server to begin listening for incoming connections. The Bridge server communicates on port 5555 at localhost.
1server.listenOnLocalhost()server : the named instance of YunServer
None
noListenOnLocalhost()Tells the server to begin listening for incoming connections. The Bridge server communicates on port 5555 at a specified address.
1server.noListenOnLocalhost()server : the named instance of YunServer
None
write()Write data to all the clients connected to a server.
1server.write(data)server : the named instance of YunServer data : the value to write (byte or char)
byte write() Returns the number of bytes written. It is not necessary to read this.
YunClientNOTE: The use of YunClient is deprecated. Use BridgeClient or the BridgeSSLClient instead.
YunClient is the base class for all client based calls on the Yun. It is not called directly, but invoked whenever you use a function that relies on it.
1YunClient clientclient : the named client to refer to
None
YunServer ConstructorNOTE: The use of YunServer is deprecated. Use BridgeServer instead.
YunServer is the base class for all server server based calls on the Yun. It is not called directly, but invoked whenever you use a function that relies on it.
1YunServer serverserver : the named instance of YunServer