oatmeal 1.1

A protocol to control and communicate with Arduino devices from Python.

Oatmeal Protocol - Control and communicate with Arduino devices from Python

Oatmeal Protocol provides a simple mechanism to autoconnect and control any Arduino-compatible microcontroller from Python over a UART serial port.

The protocol supports multiple data types including integers, strings, floats, booleans, lists, dictionaries and missing values (NULL/None/nil). It even supports nested and mixed type lists.

By using the Oatmeal libraries, developers don't need to develop yet-another bespoke protocol and all the code around parsing those messages -- and can instead focus on building cool devices faster.

Oatmeal was developed by the R&D Team @ Shield Dx and released under the Apache License 2.0. It is not an official Shield Dx product -- the code is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND. For more details please see the LICENSE file.

Python Example

from oatmeal import OatmealDevice

class MyDevice(OatmealDevice):
    ROLE_STR = "MyDevice"

board = MyDevice.find()
print("Temperature: ", board.send_and_ack("TMPR").args[0])

Arduino Example (C++)

#define HARDWARE_ID_STR "MyDevice"
#include "oatmeal_protocol.h"

OatmealMsgReadonly msg;
while (port.check_for_msgs(&msg)) {
  if (msg.is_opcode("TMPR")) {
    port.start("TMP", 'A');
    port.append(TEMP_SENSOR.read());
    port.append(OTHER_SENSOR.read());
    port.finish();
  }
}

Message structure

>>> import oatmeal
>>> msg = oatmeal.OatmealMsg("RUNR", 1.23, True, "Hi!", [1, 2], token='aa')
>>> msg
OatmealMsg('RUNR', (1.23, True, 'Hi!', [1, 2]), token='aa')
>>> msg.encode()
bytearray(b'<RUNRaa1.23,T,Hi!,[1,2]>}V')
>>>

Installation

On linux you need to run sudo usermod -a -G dialout $USER and then restart before using UART over USB. You may also have to install USB-to-UART drivers depending on the chip used.

Oatmeal Python (3.5+) Library

Simply install our Python library using using pip:

sudo pip3 install oatmeal

Oatmeal Arduino (1.8+) Library

To install via the Arduino IDE, open the IDE and navigate to 'Sketch' -> 'Include Library' -> 'Manage Libraries...'. From there, search for 'oatmeal' and install the latest version.

To install without the Arduino IDE, download the library from the git repository and copy it into your Arduino libraries folder. For more info, see the Arduino website.

Minimal hardware set up

If you are running Python on a device that has a serial port, simply connect the serial port to the arduino device:

Python device	Arduino device
Rx	Tx
Tx	Rx
GND	GND

If you are running Python on a device that has a USB port, get a USB-to-UART bridge like Adafruit's FTDI Friend or Sparkfun's FTDI Basic Breakout and make the same 3 connections as shown above. Hardware flow control pins (DTR/CTS) are not used.

Debugging

Oatmeal proxies messages over UDP to localhost ports 5551 (incoming messages) and 5552 (outgoing messages).

Listen to UDP messages with socat:

# Listen to incoming UART messages
socat -u udp-recv:5551 -
# Listen to outgoing UART messages
socat -u udp-recv:5552 -

Issues, support and contributing

License: Apache v2.0 - see license.txt.

See CONTRIBUTING.md for guidelines on submitting issues and PRs.