<img src=“https://badge.fury.io/rb/udooneorest.svg” alt=“Gem Version” /> <img src=“https://badges.gitter.im/marksull/udooneorest.svg” alt=“Join the chat at https://gitter.im/marksull/udooneorest”> <img src=“https://codeclimate.com/github/marksull/udooneorest/badges/gpa.svg” /> <img src=“https://gemnasium.com/marksull/udooneorest.svg” alt=“Dependency Status” />
This GEM provides REST service for the UDOO NEO GPIO’s, the inbuilt motion sensors (Accelerometer/Magnetometer/Gyroscope) and the Bricks Snap-in Sensors (Barometer/Temperature)
I wanted to be able to easily manipulate and monitor the GPIOs over HTTP.
Why did I choose Ruby when its not installed by default on the UDOO Neo image? No reason other than I like coding in Ruby and I have always wanted to give Sinatra a go.
As of the beta5 release of the UDOO Neo Ubunto image, there remains an issue where you will need to make a few changes to allow the udooer account to have sufficent rights to interact with the gpios. This is discussed in this forum thread (www.udoo.org/forum/threads/gpio-through-sys-class.3020/) but I have summarized what you need to do here:
1) Edit the file /etc/udev/rules.d/10-imx.rules
sudo vi /etc/udev/rules.d/10-imx.rules
2) Add the following lines:
SUBSYSTEM=="gpio", ACTION=="add", PROGRAM="/bin/sh -c 'chown -R root:ugpio /sys%p'" SUBSYSTEM=="gpio", ACTION=="add", PROGRAM="/bin/sh -c 'chmod -R g+rw /sys%p'" SUBSYSTEM=="gpio", ACTION=="add", PROGRAM="/bin/sh -c 'chown -R root:ugpio /sys/class/gpio/export'" SUBSYSTEM=="gpio", ACTION=="add", PROGRAM="/bin/sh -c 'chmod -R g+w /sys/class/gpio/export'" SUBSYSTEM=="gpio", ACTION=="add", PROGRAM="/bin/sh -c 'chown -R root:ugpio /sys/class/gpio/unexport'" SUBSYSTEM=="gpio", ACTION=="add", PROGRAM="/bin/sh -c 'chmod -R g+w /sys/class/gpio/unexport'"
3) Make the following group/user changes:
sudo groupadd -r ugpio sudo usermod -a -G ugpio udooer
4) Reboot!
sudo shutdown -r now
These instructions assume you have a fresh UDOO Neo image.
1) Install RVM
RVM (rvm.io) is nice tool to make installing and managing different versions of Ruby easy. Its not a 100% requirement, but the instructions below assume RVM is installed.
$ gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 $ \curl -sSL https://get.rvm.io | bash -s stable
Yes the \ before curl is to be included.
2) Load RVM
Either logout of your ssh session and log back in, or issue the following command to load rvm manually:
source /home/udooer/.rvm/scripts/rvm
3) Install the latest version of Ruby
$ rvm install ruby --latest
After a few minutes you will be required to enter the udooer account password:
udooer password required for 'apt-get --quiet --yes update': <password>
4) Walk away and have a nice beverage of your choosing and come back after watching a rerun of a GoT episode.
Install the udooneorest gem using rubygems
$ gem install udooneorest --no-ri --no-rdoc
To start the REST service simply issue the command:
$ udooneorest
I’ve written the API with two slightly different implementations.
The first is what you would consider a proper RESTful implementation whereby creates use POST, updates use PUT and read uses GET.
The second I created because I know many (like me) sometimes would prefer to avoid firing up a REST Console when they want some quick data. So my “lazyrest” implementation duplicates the API but using gets only (so you can simply use your browser).
The server listens on 4567 so you can access it in the following way: udooneo.local:4567/{api}
The UDOO Neo uses the GPIO in all its commands, but on the board it displays the PIN numbers (PCB Names). You can use either the GPIO or the PIN in the appropriate API and udooneorest will translate it appropriately.
Details of the GPIO to PIN mappings can be found here: www.udoo.org/docs-neo/Hardware_&_Accessories/Gpio.html
The response to the REST call will be JSON structured in the following format:
{'status' : 'success|failed', 'message' : 'If it failed, a description of why will be here'}
Exporting enables the GPIO if it hasn’t been previosly enabled. If you are using a specific GPIO for the first time, then you should export it before you will be able to set the direction or a value.
If you export a GPIO more than once, the successive export will generate a failed response.
POST /gpio/{gpio#}/export
POST /pin/{pin#}/export
GET /lazyrest/gpio/{gpio#}/export
GET /lazyrest/pin/{pin#}/export
To manipulate or read the direction of the GPIO use the following calls.
PUT /gpio/{gpio#}/direction/{in|out}
PUT /pin/{pin#}/direction/{in|out}
GET /gpio/{gpio#}/direction
GET /pin/{pin#}/direction
GET /lazyrest/gpio/{gpio#}/direction/{in|out}
GET /lazyrest/pin/{pin#}/direction/{in|out}
GET /lazyrest/gpio/{gpio#}/direction
GET /lazyrest/pin/{pin#}/direction
To manipulate or read the value of the GPIO use the following calls. The value can be 0 or 1 (low 0v or high 3v3).
If you try to set the value for a GPIO where the direction is “IN” expect an error.
Also a warning about reading the value, straight from the UDOO Neo GPIO documentation:
“If the direction is set to out and you try to read the value, it is not guaranteed that the kernel value is coherent with the voltage found on the external pinout.”
PUT /gpio/{gpio#}/value/{0|1}
PUT /pin/{pin#}/value/{0|1}
GET /gpio/{gpio#}/value
GET /pin/{pin#}/value
GET /lazyrest/gpio/{gpio#}/value/{0|1}
GET /lazyrest/pin/{pin#}/value/{0|1}
GET /lazyrest/gpio/{gpio#}/value
GET /lazyrest/pin/{pin#}/value
To manipulate and read the Accelerometer use the following calls.
PUT /accelerometer/enable PUT /accelerometer/disable GET /accelerometer/value
GET /lazyrest/accelerometer/enable GET /lazyrest/accelerometer/disable GET /lazyrest/accelerometer/value
To manipulate and read the Gyroscope use the following calls.
PUT /gyroscope/enable PUT /gyroscope/disable GET /gyroscope/value
GET /lazyrest/gyroscope/enable GET /lazyrest/gyroscope/disable GET /lazyrest/gyroscope/value
To manipulate and read the Magnetometer use the following calls.
PUT /magnetometer/enable PUT /magnetometer/disable GET /magnetometer/value
GET /lazyrest/magnetometer/enable GET /lazyrest/magnetometer/disable GET /lazyrest/magnetometer/value
To read the Temperature use the following calls.
GET /temperature/value
GET /lazyrest/temperature/value
To read the Barometer use the following calls.
GET /barometer/value
GET /lazyrest/barometer/value
Here is an example using the API to export gpio 25, set the direction to out and finally set the value to 1 (3v3).
http://udooneo.local:4567/lazyrest/gpio/25/export http://udooneo.local:4567/lazyrest/gpio/25/direction/out http://udooneo.local:4567/lazyrest/gpio/25/value/1