This software is part of a larger suite of microservices designed to remotely manage digital fabrication equipment in a loosely coupled and distributed environment. More specifically, the software in this repo implements a wrapper for the Fab Lab APIs with basic security policies. Fab Lab machines are not directly exposed to the internet, but rather they are protected by a Gateway which is the entry point to Fab Lab fabrication resources. The Gateway is responsible for managing Fab Lab access, routing incoming fabrication requests to available machines and interacting with the Cloud Hub to control fabrication status. The Fab Lab APIs wrapper has be designed to work either as a standalone application or behind a more feature-rich and general-purpose gateway as, for example, Express Gateway. All the Gateway software infrastructure can be orchestrated by a CLI that at the moment has not been open-sourced; however, the CLI is not necessary to control the Fab Lab APIs wrapper.
This software has been developed by Gianluca Cornetta and Javier Mateos within NEWTON project. NEWTON is a large scale Integrated Action, started in March 2016 and scheduled to end in summer 2019, funded by the European Commission under the Horizon 2020 Researh and Innovation Programme with grant agreement n. 688503.
- Preliminary steps
- Software and Infrastructure description
- Documentation and developer support
- Websites
- Contribution guidelines
- License
Before installing the software you have to make sure that you comply with the hardware and software requirements specified in the next two sections.
This software has been tested on a Raspberry Pi III Model B (amrv7 32-bit architecture) with a 8-GByte SD card. You need at least 150 MBytes of free disk space to install the software.
The Machine wrapper software requires that you previously install on your system the following software packages:
- Node.js >= v8.x
- npm >= v6.0.x
- Redis v4.x
- Express Gateway v1.x (optional)
We have not tested the software with Redis latest version; however it should work without any problem if you update redis client to the last version in the `package.json` file with the project dependencies.
To install the Fab Lab APIs Wrapper module go through the following steps:
- download or clone this repo,
- run
npm installin the installation folder, - run
npm run startto start the service.
The server listen to port 3000 of your Raspberry Pi.
If you plan to use the Fab Lab APIs Wrapper software behind Express Gateway you should configure Express Gateway to redirect all the incoming requests to localhost:3000. Please, refer to this link in order to suitably configure Express Gateway.
The Fab Lab APIs Wrapper (i.e. the Pi-Gateway) has been designed as an independent microservice that acts at the Fab Lab Gateway backend. The software implements features to communicate and control the Fabrication Machine Wrappers (i.e. the Pi-Wrappers). The Pi-Gateway relies on Redis to keep the status of the Fab Lab (running fabrication batches, machine status, user quotas, etc.)
All the Fab Lab management software has been written entirely in JavaScript using Node.js as the server-side platform. In Node.js, dependencies and package installation and updating is managed through the Node Packet Manager (npm). When Node.js is deployed behind a proxy npm must be suitably configured in order to work correctly.
In our specific case, the Fab Lab has been deployed in a complex enterprise network set-up that is not managed by us, but by the system administrators of our University. This means that the Pi-Gateway has neither a public IP address nor a direct access to the internet. If this is not your case, probably these considerations will not apply to you and you may skip this section.
Deploying the Fab Lab infrastructure in an enterprise network that is not managed by you, could result particularly challenging. More specifically, in our case:
- The Pi-Gateway has no direct Internet access necessary to reach the Cloud Hub infrastructure.
The Cloud Hub is tightly integrated with AWS managed services and uses Route 53 for name resolution (DNS). Unfortunately, this service is not visible from the VPN tunnel; thus, a lightweight DNS service (Dnsmasq) must be deployed on the cloud side of the infrastructure to resolve network names into IP addresses,
HA-Proxy, that is used to load balance the incoming requests among the services deployed on the cloud infrastructure, cannot work as a forward proxy; thus, it is necessary to the deploy on the cloud end also a lightweight proxy service (Timyproxy) in order to forward to the internet the requests coming from the Pi-Gateway.
Fig. 1 depicts the cloud architecture and services to allow outgoing requests from the Pi-Gateway to the internet. Observe that the Fab Lab Gateway is a router/firewall that belongs to the enterprise network. It is not part of the Fab Lab infrastructure and is managed by the our University network administrators.
Once the DNS and proxy services have been correctly configured, the npm package installed on the Pi-Gateway must be configured as well in order to correctly operate behind a proxy. This can be done by either using the npm command line interface or directly editing with your favourite editor the .npmrc file located in the Pi-Gateway home directory specifying the URL and listening port of the proxy service. Please, observe, that in the VPN configuration of Fig. 1 all the services communicate using private IP addresses. The configuration file is reported in the sequel:
proxy=http://<proxy_private_ip_address>:<proxy_port_number>
https-proxy=http://<proxy_private_ip_address>:<proxy_port_number>
strict-ssl=false
ca=null
registry=http://registry.npmjs.org
Tinyproxy is a lightweight proxy service easy to install, deploy and configure. However, there is a limitation when used with the Fab Lab APIs Wrapper. The APIs Wrapper supports both HTTP and HTTPS connection. Unfortunately, this HTTPS connections cannot be used with the actual software infrastructure because Tinyproxy does not accept incoming HTTPS connections. HTTPS connections in Tinyproxy are only supported using the CONNECT method which implies that the browser/client must know a-priori it is talking to a proxy server and use CONNECT to implement a connection.
This indeed is not a security issue since the information is already encrypted in the IPSec tunnel that connects the Fab Lab to the cloud infrastructure; however, if one would like to implement a transparent proxy supporting also HTTPS connection, Squid can be used instead of Tinyproxy. Nonetheless, Squid is not so easy to configure and deploy as Tinyproxy is.
The Fab Lab software infrastructure has been designed with the developer in mind. For this reason, Swagger has been integrated into the Pi-Gateway and the Pi-Wrapper middleware. This allow the developer to have on-line access to the API documentation and to test the native APIs through the Swagger User interface (Swagger UI). In addition, the API-first approach used to the develop the Fab Lab software allows to easily expand the software, the protocol stack and add new features adding new layers on top of the native APIs without the need of modifying the core software architecture.
Fab Lab APIs expose the underlying digital fabrication machines as software service that can be accessed from the Cloud Hub. These APIs are the entry point for the Fab Lab infrastructure and provide software methods that can be exploited to remotely control and monitor the digital fabrication machines using the cloud application interfaces. The Fab Lab APIs implement methods to get Fab Lab status and API quota, to delete a job submitted for fabrication and to send a fabrication request. Table 1 displays the resource URI and the implemented HTTP verbs for the Fab Lab APIs.
| Resource | GET | POST | PUT | DELETE |
|---|---|---|---|---|
| /fablab | Shows the Fab Lab information | Error 400 (Bad Request) |
Error 400 (Bad Request) |
Error 400 (Bad Request) |
| /fablab/quota | Shows the available API quota of the Fab Lab | Error 400 (Bad Request) |
Error 400 (Bad Request) |
Error 400 (Bad Request) |
| /fablab/jobs/status/1234 | Show the status of the job with id=1234 |
Error 400 (Bad Request) |
Error 400 (Bad Request) |
Error 400 (Bad Request) |
| /fablab/jobs?user=123&machine=laser%20cutter&process=cut&material=wood | Error 400 (Bad Request) |
Submit a job to a fablab specifying the user the machine types and the fabrication parameters in the query string |
Error 400 (Bad Request) |
Error 400 (Bad Request) |
| /fablab/jobs/1235 | Error 400 (Bad Request) |
Error 400 (Bad Request) |
Error 400 (Bad Request) |
Delete the job whose id is specified in the URL path |
API versioning is not mandatory for Fab Lab APIs.
Fab Lab APIs exclusively support JSON format.
The API error codes will match HTTP codes. The following cases are managed:
- Everything worked (success): 200–OK.
- The application did something wrong (client error): 400–Bad Request.
- The API did something wrong (server error): 500–Internal Server Error.
In the case of client and server error, the server will return in the response a JSON object with error details and hints to correct it. The message has the following format:
{code: the error code, message: the error message, details: the error details}
Table 2 reports error codes and details.
| Error Code | Error Details |
|---|---|
| 1 | Fab Lab communication error |
| 2 | Database error |
| 3 | The Fab Lab object has not been built yet |
| 4 | Unknown authorization error |
| 5 | Unknown machine error |
| 6 | Database error. Cannot read |
| 7 | Fab Lab busy |
| 8 | Database error. Cannot write |
| 9 | API quota consumed |
| 10 | Cannot connect to target machine |
| 11 | Undefined user |
| 12 | Undefined machine |
| 13 | Invalid route. Job not in database |
| 14 | Database error. Cannot delete |
The Fab Lab APIs documentation can be accessed from the Fab Lab network at the following URL:
http://gateway_name.local:3000/docs
This URL leads to the Pi-Gateway API documentation landing page depicted in Fig. 2. Please note that Swagger UI HTML code is linked to external stylesheets and javascript code; thus you must ensure your network has external connectivity in order to use this feature.
The documentation page allows navigating through the API paths and allowed HTTP verbs; for example, the screenshot of Fig. 3 depicts the documentation page of the API invoked by executing a GET request to the Fab Lab Gateway base URL.
The page shows the API description and an example of API response with 200 status code. In the case of API with content negotiation, the interface also allows selecting the response type. Finally, the interface has a “Try it out” button that allows to perform a request to the API and check the response in the web user interface. When the “Try it out” button is pressed, the user is redirected to another page that allows to submit to the API, query string parameters, forms, files, etc. (see Fig. 4). In the case of Fig. 4, the API call is very simple and has no parameters.
Finally, Fig. 5 depicts the API response obtained after pressing the execute button.
GET /fablab
Response:
200 OK
{
“fablab”: {
“id”: 1234
....
},
“jobs”: {
....
}
}
GET /fablab/quota
Response:
200 OK
{
“id”: 1234,
“quota”: 2000
}
POST /fablab/jobs?user=1234&machine=laser%20cutter&process=cut&material=wood
Response:
200 OK
{
“id”: 1234,
“mId”: 3456,
“jobId”: 4567
}
Recall, that with this method a design file in PNG format is uploaded on the server. Our API specifications correspond to the HTTP request depicted below.
POST /fablab/jobs
Host: pigateway.local/public/uploads
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryqzByvokjOTfF9UwD
Content-Length: 204
------WebKitFormBoundaryqzByvokjOTfF9UwD
Content-Disposition: form-data; name="design"; filename="design.png"
Content-Type: image/png
File contents go here.
------WebKitFormBoundaryqzByvokjOTfF9UwD--
GET /fablab/jobs/1234
Response:
200 OK
{
“id”: 1235
}
DELETE /fablab/jobs/1235
Response:
200 OK
Please see CONTRIBUTING and CONDUCT for details.
This software is licensed under MIT license unless otherwise specified in the third-party modules included in this package.