-
Notifications
You must be signed in to change notification settings - Fork 23
App Developers Guide
A FabMo app is a single page web application that is hosted by a FabMo tool. It runs in the users browser inside a software container called the "FabMo Dashboard" and usually communicates back to the tool by way of a javascript library called fabmo.js FabMo apps come bundled in packages called .fma files, which are really just zip files that have their extension changed from .zip to .fma, in order to distinguish them from zip files used for other purposes. Apps use the same web technologies (HTML,CSS,JS,etc) that are seen everywhere else, and can mostly take advantage of the same development tools and strategies that are used by other web platforms.
There are only a few absolutely necessary components of an app:
A manifest, called package.json that describes the app
An HTML page (usually called index.html) that comprises the main user interface for the app
An icon file used to display the app on the dashboard
As mentioned above, you can simply zip up the relevant files, and rename the archive, changing the extension from .zip to .fma and viola! You have an app. These aren't the only files that are needed to create an app that's really useful, though, so you'll probably want at least some of the of the following files too, depending on the needs of your app.
- Additional assets, such as CSS stylesheets, images, fonts
- fabmo.js
- Additional third party javascript libraries such as jQuery, moment.js, paper.js, etc.
- Data files and/or documentation relevant to your app
This guide is not meant to be a javascript tutorial. There are plenty of good ones out there, so the choice of third party libraries is left as an exercise for the reader.
Creating an app initially just means creating the files above, and bundling them up in an fma package. Follow the steps below.
- Create a directory to store all the files in your app
- Create a package manifest to describe your app, called
package.jsonThere is no formal documentation yet on what to include in thepackage.json, so the best thing to do at this time, is just copy the one from the example app and modify it to fit your app: https://github.com/FabMo/fabmo-example-app/blob/master/package.json - Create an index.html file, with the content of your app. Again, this isn't a tutorial on HTML or Javascript, though we'll try to provide links to some that we like. Just a basic "Hello World" HTML page will do.
- Create your icon. Icons are square, PNG format by convention. Usually we go for > 256x256px in size. If you're hard up for inspiration, you can drop the example app's icon in as a stand-in: https://github.com/FabMo/fabmo-example-app/blob/master/icon.png
- Zip up all of the files in your folder. If you're on Windows, you can do this by selecting all the files and choosing Send To->Compressed (Zipped) Folder Make sure you zip up the files not the top level folder that contains your app. Your
package.jsonmust be at the top level in the zip archive for the app pacakage to be recognized by FabMo Rename the zip archive, changing the file extension from.zipto.fma
To install your app, simply use the Install Apps... button on the dashboard and browse for your .fma archive. If you want to delete the app you've installed, you can do so from the FabMo configuration page, under "Apps"
An app with just an HTML page isn't going to do all that much on its own, so you'll pretty quickly want to move into adding functionality to your app. For this, you will want to include fabmo.js, which will allow you to make calls to the tool and to the dashboard. Functions are provided for things like moving the tool around, submitting jobs, notifying the user of events, retrieving tool configuration information and status and more. This is one place where some reference documentation actually exists: [fabmo.github.io]
Currently, there are two ways to test an app:
- Bundle it up in an
.fma, install it on the tool, and run it. - Run the app standalone, outside of the tool environment.
fabmo.js is designed so that even if you just open your app up in a browser (by opening your index.html file) it will behave sensibly, even though it doesn't have a connection to a host tool. This is the easiest way to do most of your app development. If you just view your index page in a browser, what you see there is more or less what you'll see when it's running in the dashboard's container environment. If you make API calls, such as those for submitting jobs to the tool, or driving the tool around manually, fabmo.js will try to simulate those behaviors, either by displaying a pop-up indicating what action was taken, or for job submission, downloading the g-code that would have been submitted to the tool if a tool connection was present. For apps that don't require complex back-and-forth interaction with the tool, this is the easiest way to go by far. For more complex apps, you'll have to install on the tool and tinker to get the full debugging experience, although making changes means editing, rebundling and re-installing the app. That workflow is improving, and we expect it to get more streamlined as time goes on. For an example of the behavior of fabmo.js when it is run outside a tool environment, visit any of the examples linked here: http://fabmo.github.io/fabmo.js
http://fabmo.github.io/fabmo.js provides a list of demo apps, but doesn't link directly to their source code. Here's a list of links below. If you're not into using git, you can simply download the source as a zip file, by using the "Clone or Download" button on the repository's github page.
- Example App - A simple example
- Touch and Go - Point-and-click tool navigation
- Hole Cutter - A simple parametric job
- Terrainman - More complex parametric job with some third party libraries
Below is a list of resources for app developers. It's a bit of a smattering, but may provide useful information if you're trying to get your head around how to bring your app online.
- [http://github.com/FabMo/](The FabMo Github organization site) - This includes all the repositories under the FabMo umbrella, many of which are apps that may serve as useful examples.
- http://fabmo.github.io/fabmo.js - This is the homepage for fabmo.js which includes some example API calls, and more importantly, the full, formal API documentation
- [http://demo.gofabmo.org](The FabMo Demo) - A relatively recent, running copy of the fabmo dashboard which allows you to test drive the system.