XOD is open source software development environment that can be used to programme the Arduino microcontroller board. It uses a graphical interface that represents hardware and computing elements as nodes that can be wired together to allow data flow between the objects. XOD allows a hierarchical and dataflow driven approach, avoids the complexities of text management and syntax, and can be used to directly programme Arduino boards. We think that this provides a simple way for non-programmers (i.e. biologists) to develop useful skills and understanding - without needing to deal with the complications of programming languages and syntax. We have chosen XOD as an accessible tool for Biomaker training and device development. The software can be downloaded from: (https://xod.io).
The XOD IDE (Integrated Development Environment) available in two different formats, a desktop client and a web-based client that you run in your browser. We generally use the desktop IDE. Both implementations have similar appearance and functionality, but the desktop version allows compilation on a local computer without quota limitations. There are versions of the desktop IDE for Windows, Mac OSX and Linux.
“XOD allows syntax-free programming of devices for the biology lab and the field...”— Biomaker
Patches, Nodes and LinksThe first time you open up either the desktop or web-based IDE a default project called “welcome-to-xod” will be opened. This introductory project provides a series of tutorial “patches” (see below). A patch is the working area for a XOD program. It is similar to a “sketch” in the Arduino IDE, but instead of text code - the patch is built with “nodes”, which are the basic elements in a XOD program.
A node can represent many different things: an electronic component like an LED, a sensor like the LM75 temperature sensor, a logic function like AND, OR or NOR, a pulse source like a Square Wave or Sine Wave generator, a mathematical function like multiplication or addition, a conversion function like metres to feet or a Boolean function. Each node is represented by a rectangular box that has one or more circular connections on the top and bottom. These connectors are called “pins”.
“Input pins” are located on the top side of each node, while those on the bottom are “output pins”. The pins on a node are like variables and can contain parameter values. The values can be left at their default values, or selected and set using the “Inspector”, or receive new values via connection to the output pins of other nodes.
The pins on a node can have different data types, represented by colors.
- Green Pins represent numbers.
- Blue pins represent pulses.
- Violet pins represent boolean values.
- Orange pins represent strings.
A XOD program consists of nodes connected together in one or more patches. New nodes are selected in the Project Browser, and dragged onto the patch area. If you know the name of the node you want to add, you can double-click on a blank area of the patch or press the ”i” key on your keyboard. This will bring up a search box where you can type in the name of the relevant node. If the search is successful, highlight the node in the results and hit “enter” to put the node onto the patch.
In XOD “Links” are the lines used to connect nodes to each other. A link runs from an output pin on one node to the input pin on another node.
You create a link by clicking on a pin on one node, this created the starting point of the link. You then drag it to another pin on another node. You can start creating a link by clicking on either an input or an output pin.
XOD is smart and won’t let you link a pin to another pin if it doesn’t make sense or if the data types are incompatible. The link color is determined by the data type of the output pin in the link.
Linking nodes is a lot like wiring elements in an electronic circuit. In fact a XOD program really looks more like a wiring diagram than anything else.
Project BrowserThe Project Browser is a section on the top left side panel of the XOD IDE. It essentially allows you to manage all of the patches in your project and to add nodes. It consists of the following sections:
- Project Patches – A list of all of the patches used in your project. You can open, rename or delete each patch or even drag it onto another patch.
- Custom libraries
- xod/bits - Low-level bits and bytes operations
- xod/color - Library to work with color
- xod/common-hardware - Hardware drivers for popular and simple peripherals
- xod/core - The very basic nodes of XOD
- xod/datetime - Date and timestamp operations
- xod/debug - Debug nodes for XOD
- xod/gpio - Nodes of XOD to deal with GPIO (hardware pins)
- xod/i2c - I²C (aka I2C, IIC, TWI) bus interfacing
- xod/math - Nodes of XOD for basic mathematical operations
- xod/net - No description
- xod/stream - No description
- xod/uart - Provides constructors and Nodes to interact with UARTs (Software, Hardware, USB) in XOD.
- xod/units - Units of measurement conversions
- xod-dev/ds-rtc - This library operates DS1302/DS1307/DS3231 based breakout RTC boards
- xod-dev/esp8266 - Support for ESP8266 as a slave module
- xod-dev/esp8266-mcu - Support for ESP8266-based MCUs.
- xod-dev/pn532-nfc - Support for RFID/NFC modules based on a PN532 chip.
- xod-dev/sharp-irm - Nodes to read analog infrared range meters by Sharp (GP2Y0A) and convert the signal to distance values.
- xod-dev/w5500 - Support for ethernet shields that use Wiznet W5500 chipset.
The Inspector is located on the bottom left side of the XOD IDE. It allows you to view and modify the properties of nodes. If you highlight a node the Inspector will display its current properties. Each pin in the node will have a property. You can modify the properties of most input pins if they are unconnected. If a pin is connected to the output of another node then the pins property will be controlled by that node and you won’t be able to modify it. You can rename a node so that it makes sense in your project. This is useful if you have several nodes of the same type, for example several LED nodes. You can also add a description to each node if you wish.
Quick HelpThe Quick Help section is on the top right of the XOD IDE. By default it is hidden but you can toggle it on by clicking on the “question mark” icon in the top right corner. Quick Help gives you information about the highlighted node and its pin functions and data types. It’s very useful and I would recommend keeping it open at all times. Between the Inspector and the Quick Help you can usually get enough information to work with any XOD node.
Introductory lessons for XODThere are variety of introductory lessons for XOD, available at: https://xod.io/docs/tutorial/ - an example is shown below.
Simply install the cross-platform XOD software, assemble and plug in the hardware, and you can get started directly. In addition to these introductory exercises with minimal hardware, we will be running sessions with extended componentry, that we will build on during the training course.
- Installing and running XOD
- Required hardware
- Hello
- Upload to Arduino
- Pins, data, and the Inspector
- Fractional numbers and PWM
- Wiring configuration
- Adding nodes
- Node labels
- Constant nodes
- Input from a potentiometer
- Doing math
- Controlling servos
- Accessing help
- Mapping values
- Adjusting map range
- Buttons
- Logic nodes
- Reading lightness
- Comparing numbers
- If-else branching
- Smoother changes
- Pulses
- Clock
- Pulse counting
- Flip-flop
- Using multiple timelines
- Showing text on LCD
- Displaying sensor values on LCD
- String concatenation
These tutorial exercises can be run outside of the Biomaker training sessions - to give a fuller range of experience with the programming interface and nodes. The required hardware can be found in the Starter Kit.
A XOD tutorial library with basic patches can be found at https://xod.io/docs/tutorial/ (some of these may require adjustment of parameters for use with the multifunction Rich UNO R3 board provided in the Biomaker Starter Kit).
In addition, an excellent collection of hands-on hardware-software tutorials that can be found at the XOD website (https://xod.io/docs/guide/). These are summarised below. The same web page also includes details of Interfaces and protocols: Controlling LEDs via UART — exchanging text-based data between two boards, I²C communication basics, IoT and Network communication: Quick setup of W5500 Ethernet Shield for Internet and LAN communication, Advanced setup of W5500, Connecting to Internet with ESP8266-based MCUs, Fetching data from web API’s with HTTP GET requests.
Digital clockA tutorial that descibes the use of XOD nodes to conbine a real time clock (RTC) module and I2C 16x2 LCD text display to create a digital clock. The tutorial exercise is easily translated to the Rich UNO R3 board and Starter Kit, with access to the onboard RTC, expansion shield and external I2C 16x2 LCD display. The tutorial provides a detailed description of the software and hardware components - and is especially useful for its clear description of the way patched nodes can be encapsulated in a single new node with particular inputs and outputs - and embedded in another patch. This allows functions to be embedded in a modular and reusable way - and can shield users from underlying complexity.
This example describes how to use the datetime and ds-rtc libraries, format date and time values, and work with real-time clock (RTC) modules for Arduino. Upon the completion of the guide, you learn how to create a simple digital clock based on a DS1307 I2C RTC module and I2C LCD display.
In this example, the programming process consists of two steps:(i) Making a program to write the current datetime to the memory of the RTC module. (ii) Making a program to read the current datetime from the RTC module and display it on the screen.
The instructions and code can be found at: https://xod.io/docs/guide/rtc-example/
Required hardware:Arduino Uno board e.g. Rich UNO R3I2C RTC breakout board based on the DS1307 microchipI2C LCD 16x2 displayA battery to power the RTC moduleExpansion shield or breadboardHook-up wires
Experiments:(i) Reformat the time display(ii) Direct the output to different displays, ie. the onboard 4-digit display or 4D Systems touchscreen display
This tutorial describes how to store sensor data and process it on a computer. The example shows how to read environmental temperature and save the values on a microSD card. After this, the microSD card can be connected to a computer to analyze the measured sequence of temperature values.
The example employs a TMP36 based thermometer, but XOD also supports the LM75 temperature sensor that is installed on the Rich UNO R3 board. The LM75a-temp-sensor node can be found in the gst/lm75atempsensor XOD library, and can be added to the patch. The LM75 thermometer is connected via an I2C port.
Note: there is more information about use of the Rich UNO R3 RTC and LM75 devices in XOD in Tutorial 3.
The temperature readings are bound to timestamps when read, using a system-time node. This node outputs time in seconds passed since the program start. A count node is used to number each new record for the continuously updated data. We need to set a frequency of readings to limit the data volume and to give some time for the microSD board to flush the file after each record. The easiest way to do this is to use a clock node.
With a potentially large volume of data, the stream can be formated as a table. Each row may represent a single record: the record number, record timestamp, and a temperature value read at that moment. To combine all data values and store them as a single string, use the join node. XOD provides an sd-log node to append text lines to the tail of the specified file stored on an SD card.
The program can be uploaded to the Arduino board and optionally powered by battery/solar cell. The program will be held in non-volatile memory, and the device will continute logging whenever powered, and despite any interruptions due to power loss. With the microSD card, you can store a significant amount of data that would not fit in the memory of the controller.
The instructions and code can be found at: https://xod.io/docs/guide/sd-log-example/
Required hardware:Arduino Uno boardLM75 digital temperature sensormicroSD breakout boardFormatted microSD cardBreadboardHook-up wires
Experiments:You can use any other sensor or even several different sensors to log and observe a processes of your choice.
A traffic light is a good example of a device which does its job sequentially. In its simplest form a traffic light has three states: Green — go, Yellow — stop if you can and Red — stop! Each state is active for some time interval and when done everything starts from the beginning and repeats again and again.
The tutorial describes the implementation a state machine. In this example there is one patch node per state and a patch that will wire the state nodes together. In this case: (i) state-green, (ii) state-yellow, (iii) state-red and (iv) main joining patch.
Drafts are crated for all state patches, the main patch is built, and then finalised. A mechanism is needed to allow patch nodes to talk to each other. A common mechanism is to send a pulse input to a state patch to enter that state, and add pulse outputs to notify about state completion. Therefore, each of the states has an input and output. We can wire them in a daisy chain so that when one state completes its job, it gives the control to the next state.
What should a state do once entered? When should it exit? What should it do right before exit? In this case, when a state is entered, it should turn on the corresponding LED. Then it should wait few seconds, turn the LED off and then exit.
A pulse from a boot node is used to trigger entry into the first state, as we want our traffic light to start its job right when the device is powered up. However, the device suspends after the last state because nothing returns it back to the first state. We could link the last state DONE pulse to the first state SET pulse to complete the loop, but unfortunately, XOD does not allow this - to avoid possible deadlocks. Instead we can add a defer node. This can break any cycle and tell XOD to break off if a deadlock occurs. The first state-green node input is not allowed to have links from the boot and defer-pulse at the same time. We can easily solve it by adding an any node.
Doing things sequentially in XOD requires the following approach:(i) Understand your sequence states(ii) For each state make a patch node(iii) On each state patch, use pulse inputs and outputs to enter and exit the state(iv) Make a joining patch which wires all states together(v) Define an entry pulse for the first state
The instructions and code can be found at: https://xod.io/docs/guide/simple-traffic-light/
Experiments:Play with timeout values, try to start the sequence from another state, add three more LEDs to form a complementing traffic light.
Required hardware:Arduino Uno boardOnboard TMP75 I2C temperature sensormicroSD breakout boardFormatted microSD cardBreadboardHook-up wires
Marco Aita and Carlos Lugo have rewritten this for use with the shield and RGB LED.
Jim Haseloff
Comments