oddWires IoT-Bus Operator's manual

iot-bus Documentation
Release latest
oddWires
Mar 05, 2019

IoT-Bus Introduction
1 IoT-Bus Overview 3
2 IoT-Bus Pinout 13
3 Choosing a Platform and Framework 15
4 Getting Started with PlatformIO 17
5 Getting Started with Arduino 19
6 Getting Started with esp-idf 21
7 Getting Started with Mozilla IoT 23
8 Getting Started with Micro-Python 29
9 Getting Started with Moddable 31
10 Getting Started with MicroBlocks 33
11 Io 35
12 Proteus 39
13 JTAG 43
14 2.4” QVGA Touch Display 47
15 Motor 51
16 Relay 53
17 CAN Bus 55
18 LoRa 57
19 IoT-Bus Examples Index 61
20 IoT-Bus Blink Example 63
i

21 IoT-Bus Hello World Example 65
22 IoT-Bus Touch Draw Example 67
23 IoT-Bus Relay Example 73
24 IoT-Bus CAN Bus Example 75
25 IoT-Bus LoRa Example 79
26 IoT-Bus Motor Example 83
27 IoT-Bus SD_MMC Card Example 85
28 IoT-Bus Mozilla IoT Examples 91
29 IoT-Bus LED Touch Thing 95
30 IoT-Bus LED Thing 97
31 IoT-Bus LED Lamp Thing 99
32 IoT-Bus Relay Thing 103
33 IoT-Bus Relay Display-Touch Thing 105
34 IoT-Bus Window and Door Sensor Thing 111
35 IoT-Bus DHT11 Thing 113
36 IoT-Bus HC-SR04 Thing 119
37 IoT-Bus HC-SR501 PIR Thing 123
38 IoT-Bus Calculator Thing 127
39 IoT-Bus Mozilla IoT Tutorials 135
40 LED Thing Tutorial 137
41 Touch Switch Thing Tutorial 143
42 Mozilla Rules Engine 149
43 Frameworks 155
44 Platforms 157
45 Espressif32 Key Features 159
ii

iot-bus Documentation, Release latest
IoT-Bus Introduction 1

iot-bus Documentation, Release latest
2 IoT-Bus Introduction

CHAPTER 1
IoT-Bus Overview
The oddWires IoT-Bus system is based on a low-cost, open design that includes multiple main boards including a
minimalist, breadboard-friendly form-factor, the IoT-Bus Io and a version with a large prototyping area which enables
a single-board IoT solution, the Proteus.
The IoT-Bus is designed to be “plug and play” - the new range of oddWires open IoT-Bus boards use the Espressif
ESP32 microprocessor (240Mhz, 32-bit, 4MB) for rapid, low-cost IoT development and deployment.
Our aim is to provide an open platform, easy to adopt and build on, adaptable, tested, with many solutions already
available. There are no lock-in costs, and overall it provide a low-cost solution for faster development of professional,
educational and hobbyist applications.
A variety of programming languages, environments and frameworks that work right out of the box with IoT-Bus and
PlatformIO supports most of them in a professional or serious educational or hobby environment. You can use either
the esp-idf framework for a professional multi-tasking system based on freeRTOS or the popular Arduino environment
for simplicity.
So take your choice! Other platforms include javascript by Moddable, the Mongoose server or python by MicroPython.
There’s even a graphical way of programming IoT-Bus - microBlocks.
3

iot-bus Documentation, Release latest
Some IoT-Bus Boards
1.1 IoT-Bus System
• Open Design
• Low-cost
• Plug and Play, Expandable
• Powerful 240MHz, 32-bit Processor with 4Mb of Flash Memory
• Multiple Form Factor Main Boards (Io, Proteus)
• Connected in Many Ways (Wi-Fi, Bluetooth, BLE 4.0. LoRa and CAN Bus are available options)
• Integrated 2.4” Touch TFT QVGA Display Available
• Solder-able Prototype Board with Controller
• IOT-Ready, Relay and Motor Controller
• Multiple open platforms
• Supports C++, MicroPython and javascript
At the heart of the system is an ESP32 processor providing two SPI and an I2C interface with plenty of general purpose
I/O. The Espressif ESP-WROOM-32 has been selected as the micro-controller enabling very low-cost deployment of
production IoT devices. It offers 240Mhz, 32-bit processing with 4MB of flash as standard.
4 Chapter 1. IoT-Bus Overview

iot-bus Documentation, Release latest
The first controller boards drive relays and motors and there are a wide range of connectivity options including Wi-Fi,
Bluetooth, CAN Bus, and LoRa.
Developing open IoT applications means being able to see the schematics for the hardware, using open tools, frame-
works and platforms and very importantly the cloud you use has to be open.
1.2 Mozilla Project Things - An Open Internet of Things
Internet of Things (IoT) devices have become more popular over the last few years, but there is no single standard for
how these devices should talk to each other. Each vendor typically creates a custom application that only works with
their own brand. If the future of connected IoT devices continues to involve proprietary solutions, then costs will stay
high, while the market remains fragmented and slow to grow. Consumers should not be locked into a specific product,
brand, or platform. This will only lead to paying premium prices for something as simple as a “smart light bulb”.
We are aligned with mozilla and believe the future of connected devices should be more like the open web. The future
should be decentralized, and should put the power and control into the hands of the people who use those devices.
This is why we are committed to supporting open standards and frameworks.
We are partnering with mozilla to offer kits that can be used to quickly integrate with mozilla-iot. Watch this space for
more details. We have also created many examples using iot-bus with mozilla-iot. See our examples on github.
1.3 Two main-board form-factors
Io Very small and breadboard-friendly with option of male, female or both (stackable headers). Includes a dual-core
240 MHz ESP32 with WiFi and Bluetooth. You can use the WiFi both in station (device) mode and access point
mode. It includes traditional Bluetooth as well as BLE 4.0.
On-board is a 3.3V regulator and a battery charging device that enables you to switch between using USB
or battery power. The battery is automatically charged in the USB is plugged in. A status light shows if
it is charging or fully charged. All ESP32 pins bar the flash pins are exposed and available for your use.
Proteus This board is larger and designed to make it possible to add your own circuitry to make a complete IoT
solution on one board. It includes a dual-core 240 MHz ESP32 with WiFi and Bluetooth. You can use the
WiFi both in station (device) mode and access point mode. It includes traditional Bluetooth as well as BLE 4.0.
On-board is a 3.3V regulator and a battery charging device that enables you to switch between using USB or
battery power.
The battery is automatically charged in the USB is plugged in. A status light shows if it is charging or fully
charged. All ESP32 pins bar the flash pins are exposed and available for your use.
The board includes a large prototyping area that includes room for traditional DIP and through-hole components
as well as SMD parts such as SOIC and SOT-23. A user LED and switch is included but not connected to any
pins so you can use them how you wish. Two level shifters are included so you can interface with 5V devices.
The Proteus includes both 3.3V and 5V rails. Both these rails are available whether powered by the USB or the
battery as the 5V is derived from the lower voltage.
1.2. Mozilla Project Things - An Open Internet of Things 5

iot-bus Documentation, Release latest
Fig. 1: Io
1.4 JTAG
Both the Io and Proteus processor boards can accept a specially designed JTAG board offering hardware debugging.
Our JTAG board is based on the FT232H and it enables comprehensive JTAG debugging support. You can use
OpenOCD and GDB in combination to use it but our recommendation is to use PlatformIO. PlatformIO has taken
away all the hard work of configuring OpenOCD and GDB. You simply select it is your debugging choice as described
here. Take a look at how easy it is to use with PlatformIO’s Unified Debugger. Just plug it in and start debugging! No
more printing to the terminal!
6 Chapter 1. IoT-Bus Overview

iot-bus Documentation, Release latest
Fig. 2: Proteus
1.5 2.4”
QVGA TFT
Touch Dis-
play
This a nice 2.4”
320x240 QVGA
TFT Touch Dis-
play offering plug
and play display
output and touch
sensing together
with a 4-bit SD-
MMC SD Card.
We picked 2.4”
over 2.8” as it has
a crisper display
at 320 x 240 res-
olution and its
slightly smaller
size helps in IoT applications. Designed primarily for development use it has an IoT-Bus socket at the side.
1.5. 2.4” QVGA TFT Touch Display 7

iot-bus Documentation, Release latest
1.6 Two
Ad-
di-
tional
Con-
nec-
tiv-
ity
Op-
tions
CAN Bus
The
IoT-
Bus
CAN
Bus
mod-
ule
of-
fers
a
transceiver
that
en-
ables
you
to
use
the onboard ESP32 CAN controller. You can connect the terminals to any required connection.
LoRa
This
IoT-
Bus
mod-
ule
uti-
lizes
the
Hope
RFM95
to
of-
fer
low-
cost,
LoRa
ra-
dio transmission and a Wi-Fi/LoRa gateway. It uses the correct 915 MHz rather than the 433 MHz european standard
8 Chapter 1. IoT-Bus Overview

iot-bus Documentation, Release latest
often found. The RFM95W transceivers feature the LoRa long range modem that provides ultra-long range spread
spectrum communication and high interference immunity whilst minimizing current consumption.
Using
Hope
RF’s
patented
LoRa
mod-
u-
la-
tion
tech-
nique
RFM95W
can
achieve
a
sen-
si-
tiv-
ity of over -148dBm using a low cost crystal and bill of materials. The high sensitivity combined with the integrated
+20 dBm power amplifier yields industry-leading link budget making it optimal for any application requiring range
or robustness.
LoRa™
also
pro-
vides
sig-
nif-
i-
cant
ad-
van-
tages
in
both
block-
ing
and
se-
lec-
tivity over conventional modulation techniques, solving the traditional design compromise between range, interference
immunity and energy consumption. These devices also support high performance (G)FSK modes for systems includ-
ing WMBus, IEEE802.15.4g. The RFM95W deliver exceptional phase noise, selectivity, receiver linearity and IIP3
for significantly lower current consumption than competing devices.
1.6. Two Additional Connectivity Options 9

iot-bus Documentation, Release latest
Fig. 5: CAN Bus
1.7 Two
Controller
Boards
Relay This is an opto-
isolated relay board
driven by a single
digital pin. It is a
110V, 10A maximum
AC relay board in the
IoT-Bus form factor.
Motor This IoT-Bus mod-
ule provides a motor
controller. It uses
two TB6612FNG mo-
tor drivers controlled
by a PCA9685 on the
I2C bus. It supports
two stepper motors or
four DC Motors.
10 Chapter 1. IoT-Bus Overview

iot-bus Documentation, Release latest
Fig. 7: Relay
1.8 Platforms
Name Description
Espres-
sif32
Espressif Systems is a privately held fabless semiconductor company. They provide wireless communica-
tions and Wi-Fi chips which are widely used in mobile devices and the Internet of Things applications.
1.9 Frameworks
Name Description
Ar-
duino
Arduino Wiring-based Framework allows writing cross-platform software to control devices attached to a
wide range of Arduino boards to create all kinds of creative coding, interactive objects, spaces or physical
experiences.
ESP-
IDF
Espressif IoT Development Framework. Official development framework for ESP32.
1.8. Platforms 11

iot-bus Documentation, Release latest
12 Chapter 1. IoT-Bus Overview

CHAPTER 2
IoT-Bus Pinout
13

iot-bus Documentation, Release latest
Fig. 1: IoT-Bus Pinout
14 Chapter 2. IoT-Bus Pinout

CHAPTER 3
Choosing a Platform and Framework
One of the great things about IoT-Bus is that you’re free to choose from a large number of platforms and frameworks.
You know that you want to create an IoT project but where do you start? In our view it very depends on what you
know now.
3.1 Arduino
If you have never programmed or know nothing about embedded hardware then you may be best to start with Arduino
as a framework and as an editor and programmer. Similarly, if you are in education and do not want to be explaining
things to yous students about the IDE and just want to create very simple applications then again, you may pick
Arduino as a Framework and as your development environment. Many, many users have chosen Arduino overs the
years and many still do. It’s a great place to start. You’ll find more projects on the web that Arduino based so if you
want to find somebody that’s done something similar to what you want to do. You’ll probably find it as an Arduino
project somewhere.
3.2 PlatformIO
On the other hand if you are a professional programmer or a serious hobbyist then you will probably pick PlatformIO.
There are other environments that are just fine if you already use them like Eclipse or NetBeans. But if you are
investing your time and money in the future then PlatformIO is the way to go. It’s also not hard to take that same
project and import it into PlatformIO and take it from there.
Similarly, if maintaining source code integrity, versioning and testing and debugging are becoming more important you
as a Arduino user then take a look at PlatformIO. The advantage that PlatformIO has taken of leveraging an excellent
open IDE from Microsoft and extending it, again, in open fashion to the embedded world If you’re a seasoned C++
programmer then PlatformIO and the esp-idf framework is probably the way to go.
Now in terms of framework you again have a choice. Arduino or esp-idf are the c++ development choices. Arduino is
simpler and more “black-box” - you can get going very quickly and without necessarily fully understanding everything
you can get an IoT project up and running. However, if things like a multi-tasking environment and the availability of
professional-class libraries and support are more important then esp-idf is more likely to be the framework for you. It
15

iot-bus Documentation, Release latest
is lower-level and you may have to do more work but you are also more likely to get a professional application as a
result.
There is a “third-way” option of using Platformio as your development environment and using Arduino as your frame-
work if you are a new user or already familiar with Arduino libraries. This option perhaps gives you the best of both
worlds. You’re able to get up and running quickly and it would be easier to move to esp-idf you should choose to.
3.3 MicroPython
Python is becoming ubiquitous (this documentation was produced using it!). And MicroPython is a great implementa-
tion of python for the embedded environment. So if you are already familiar with python that’s a great way to leverage
the IoT-Bus system. We’ll show you later in this section how to get started with it.
3.4 Moddable
Javascript is another great alternative. It’s not only used in front-end code, there are dedicated servers for it and a whole
development infrastructure that has sprung up around it. And Moddable is the company that just “does javascript right’.
We’ll show you later in this section how to get started with it.
3.5 MicroBlocks
Lastly there are other choices that may be even better when teaching students graphically such as MicroBlocks which
runs wonderfully on IoT-Bus and does not require traditional line-by-line programming.
3.6 Mozilla-IoT
Now Mozilla IoT is not a platform in the same sense of others here. But it certainly is a platform for IoT and
irrespective of the framework or the language you can take advantage of Mozilla IoT to discover, inspect and control
your IoT devices. So if you’re thinking about a smart-home, a home security project or simply want the ability to
control a device at home from your phone or PC then do look at Mozilla IoT
3.7 Summary
So what would I do today?
1. Buy a kit from oddWires.
2. Choose a platform/framework. You can’t really go wrong. Your investment in IoT-Bus will work in every case
and you can change your mind!
3. Get started with IoT-Bus and Mozilla IoT!
16 Chapter 3. Choosing a Platform and Framework