nobel
Nobel (code-generator) creates a REST API for your Arduino board, based on a SWAGGER or RAML definition.
Description
Nobel scaffolds an Arduino application that exposes a REST API. Then, you can write the logic for interacting with your physical devices inside methods that will be executed when the corresponding URL is invoked.
Example
Considering the following Swagger code:
swagger: "2.0"info: version: "0.0.1" title: NobelTestingAPIpaths: /servo: post: description: | Moves the servo to the specified angle. parameters: - name: angle in: body description: angle object required: true schema: $ref: '#/definitions/Angle' responses: 200: description: Successful response schema: $ref: '#/definitions/Angle' put: description: | Moves the servo buy Adding the specified angle (could be negative) parameters: - name: angle in: body description: angle object required: true schema: $ref: '#/definitions/Angle' responses: 200: description: Successful response schema: $ref: '#/definitions/Angle' get: description: | Returns the current servo angle responses: 200: description: Successful response schema: $ref: '#/definitions/Angle'definitions: Angle: description: Task object properties: angle: type: integer description: task object name required: - angle
or the following RAML code
#%RAML 0.8 title: NobelTestingAPI/servo: post: description: | Moves the servo to the specified angle. body: application/json: example: | {"angle": 71} put: description: | Moves the servo buy Adding the specified angle (could be negative) body: application/json: example: | {"angle": -10} get: description: | Returns the current servo angle responses: 200: body: application/json: example: | { "angle": 71 }
Nobel generates a project with several files (following the Arduino specs for splitting a program). One of the files contains the Handlers, where you can write your own code. Associated to the RAML example:
// Handlers void
Installation
Pre-requisites
- NodeJS
- NPM
- Arduino development environment (This is not needed to run Nobel, but will be needed to make something useful with it).
Install Nobel
Installing Nobel is really simple.
- Open a terminal/command line
- type
npm install -g nobel
... That's all you need.
Usage
Nobel is a Command Line Interface (CLI), which means that you will be executing it from a terminal/command line (I don't see a clear value on building a GUI for this).
nobel -s [your_swagger_or_raml_file] -n [your_project_name]
The line above shows the minimum parameters set you need to specify in order to scaffold an Arduino Application using Nobel. The result is:
.└── myArduinoRobot ├── A_functions.ino ├── B_definitions.ino ├── C_handlers.ino ├── D_initialization.ino └── myArduinoRobot.ino
You can find a description of each file in the following sections.
Arguments
Argument | Required | Description |
---|---|---|
-s --source | YES | The Swagger or RAML file describing the API to implement on the Arduino program. |
-n --name | YES | The name of your project. Nobel will create a folder with this name, and one main project file inside named like this. |
-t --target | NO | The target directory where the project will be placed. If not specified, the project will be created on the folder where you are running Nobel. |
-il --installLibraries | NO | If specified, it installs the required Arduino libraries on the folder you specify. Click here to figure out where this folder is. |
-h --help | NO | Really? Yes, the user manual will be printed in the terminal/command line |
Once your app is there
- You just need to open the project with the Arduino IDE (you can use your preferred one, but all this project has been made using the Official Arduino IDE). Important: If you are installing libraries, you will need to restart the Arduino IDE for those to be recognized (I can't do anything about it. Arduino IDE has some tricky parts. Get over it ;)).
- Compile: If it's not working, something is wrong. Nobel is thought to scaffold a right-away working application (that won't do anything until you put your code on it). If anything goes wrong at anytime, create an issue
- Put your own code!
Files
Coding in Arduino is really a lot of fun (despite of/becouse of/but/your choice) it presents some challenges. The main one here: Memory. There could be better ways of implementing the code Nobel creates, but I haven't found it yet (feel free of making your own suggestions. That won't hurt my feelings at all). Because of this, I needed to hardcode some values (yes, shame on me). You only need to worry about it if you need to manually add new resources. If not:
- [your_project_name].ino: Main file. It only includes the libraries required by all of the other files. No need to touch at all.
- A_functions.ino: Contains functions that will be used by the application to parse and route the URLs to the proper handlers (It is not that simple to put these into a library, thanks for asking).
- B_definitions.ino: You will probably need to define some variables that you will use later in a global way. Even though you will probably initialize these
on
D_initialization.ino
, you will use these inC_Handlers.ino
, and, since Arduino concatenates in alphabetical order (excepting for the main file), not declaring the variables here, will result in errors. - C_Handlers.ino: You will write your logic here!!! A function will be generated per each result, and a SWITCH CASE inside of it, to determine the HTTP verb being invoked (this could be changing in the future, supporting other code styles. For Example: One function per Resource-Verb combination)
- D_Initialization.ino: You need a place where everything starts. The
setup
andloop
functions (which Arduino calls when booting) are placed here for you to complete as needed.
Seeing the example is the best way of understanding how to code.
Note: The scaffolded application will use DHCP. You can find the code to change this in the D_Initialization.ino
file (setup
function)
Manually Adding new resources
Sorry! I'll try to improve this, but this far, for an MVP, it is what it is!
Don't bother reading this if you are NOT manually adding new resources.
A_Functions.ino
- Since
sizeof
function is not properly working, I needed to hardcode the resources array length on the very first lin:const byte SIZE_RESOURCES = 5; // constant until resolve what's going on with sizeof
. Change it if you manually add or remove resources. - Since I'm using a FLASH_ARRAY (basically for placing big amounts of data in the program memory instead of the variables space), I can't freely use an array and pass pointers as parameters or return these. So, the array needs to be defined inside the function that will use it. ugh indeed.
When adding one, you will also need to add the proper Handler in D_Initialization.ino
D_Initialization.ino
- Add a new handler:
void
Important: The order is the way of matching a resource with it handler!!! It's much more efficient and doable than trying to do some kind of "reflection". So, make sure of adding the handlers in the same order than the resources on the previous step.
Now, a handler, is basically a pointer to a function (Nobel places these functions on C_Handlers.ino
). So, if you have &resourceAHandler
, you will need:
C_Handlers.ino
void
Hands On Example
Create the API definition file.
You can choose to define your API by using Swagger or RAML. It's up to you ;)
Swagger
swagger: "2.0"info: version: "0.0.1" title: NobelExampleAPIpaths: /led: post: description: | Turns the light on responses: 200: description: Successful response delete: description: | Turns the light off responses: 200: description: Successful response
RAML
#%RAML 0.8 title: NobelExampleAPI/led: post: description: Turns the light on delete: description: Turns the light off
and save it (the example asumes that it will be called swaggerExample.yaml
or ramlExample.raml
)
Scaffold the application
For Swagger
nobel -s swaggerExample.yaml -n ledController
For RAML
nobel -s ramlExample.raml -n ledController
or
For Swagger
nobel -s nobelExample.raml -n ledController -il [path_to_your_arduino_libraries_directory]
For RAML
nobel -s nobelExample.raml -n ledController -il [path_to_your_arduino_libraries_directory]
if you haven't ever installed the required libraries.
Put your own code
- Open the IDE.
B_Definitions.ino
Add this line:
byte ledPin = 9; // It's a good practice to use a variable to semantically represent your Arduino output.
D_Initialization.ino
Add this line in the void setup()
function
// We are specifying that the pin 9 will be used as an output.
The function code should look like this:
void
C_Handlers
// Turns the led on // Turns the led off
Let's add both calls to the POST
and DELETE
methods, and the final code should look like this:
void
Compile and deploy
By default, the generated code will make Arduino take an IP by using DHCP. Open a Serial Monitor to see the assigned IP. In order to test the app, use any program capable of sending HTTP messages via network. Postman extension for chrome is my favorite.
- POST http://[the_ip_DHCP_assigned]/led (should turn the led ON).
- DELETE http://[the_ip_DHCP_assigned]/led (should turn the led OFF).
Contributing to this code
- If you are using Atom, please make sure that the following configuration is correct. If not, it will add or remove "\n" and spaces characters from your templates making the unit tests to fail
Credits
- Without any doubt, I would have quit the idea of creating this project if I didn't find a good HTTP server for Arduino. So, it wouldn't be possible at all without Webduino by sirleech. Thanks to him and his amazing job.
- 2 KB for all my variables? Where to put the resources array? In the Program Memory!!! That is possible thanks to the Flash module by mikalhart.