The Courier project is broken down into four pieces - Agent, Engine, Server & Admin Console - and is divided up between three different repos.
- Agent - https://github.com/makeandbuild/courier-agent-nodejs
- Server & Admin Console - https://github.com/makeandbuild/Courier
- Engine - https://github.com/makeandbuild/courier-agent-engine
For a high level overview including architecture diagrams refer to our blog post Courier iBeacon Implementation
We chose to write the server in Node.js using the Express framework to get everything up and running quickly. Node allowed us to get our web server running in just a few lines of code and Express helped simplify building the REST API. We started out using REST for all communication with the server but have since started using WebSockets with socket.io as well. Most notably we switched to WebSockets for communication with agents to remove the overhead of HTTP when publishing detections to the server every two seconds.
Once the server receives a detection payload from an agent, it saves the detections to a MongoDB database and analyzes them to determine which beacons came in range for the first time, which ones are still in range, and which ones are no longer detected - enter, alive, or exit events respectively. Based on the event type, we send action commands to the configured engines. Currently we send commands to play audio files when we receive an enter event for a beacon, but you can customize this to do whatever you want.
var engineNamespace = socketio.of('/engine');
engineNamespace.to(engineId).emit('playaudio', { filename: 'hello.wav' });WARNING: DOCS ARE NOT UP TO DATE YET We haven't had time to fully document the API so until then you are probably better off just refering to the code itself. All the REST endpoints can be found in the server/api folder. The files are named like agent.controller.js.
Most of the site is still in boiler plate sample format. The only pages that are currently up to date are the following:
- Authenticate - http://makeandbuild.github.io/Courier/#/authentication
- Response Format - http://makeandbuild.github.io/Courier/#/response-format
- GET /beacondetections - http://makeandbuild.github.io/Courier/#/get-beacon-detections
- POST /beacondetections - http://makeandbuild.github.io/Courier/#/post-beacon-detections
For everything else please refer to the documentation in the code itself.
Development is in the gh-pages branch.
Current docs can be viewed at http://makeandbuild.github.io/Courier/
The service layer code is located in the server/service folder. The files are named like agent.service.js.
The DAO layer uses MongoDB. The code is located in the server/dao folder. The files are named like agent.dao.js.
This is the code that is responsible for taking actions based on the enter, alive, and exit events for the beacons. Eventually we want to pull this code into a separate module/code base. In preparation for that we send events to it using socket.io instead of making direct calls to it. We have separated the code to its own server/rules folder so that it is easy to separate when we have time.
Any custom actions you want to take when an event is recieved should be registered in detection.event.service.js by passing the behavior/rule as a function to the registerRule(ruleFunction). When an event is detected all registered rules will be processed.
If you open app.js you'll see a section where we are manually registering the rules engine and the specific rules for it. You should continue to follow this pattern for now.
// Configure rules engine
require('./rules/service/event.subscription.service').register();
require('./rules/plugins/audio.rule.js').register();
require('./rules/plugins/employee.location.rule.js').register();The admin console is written in Angular.js and connects to the server using its REST API. You can use it to manage and check the status of your agents, beacons, and engines. You can also view a list of the saved detections.
The source code comes with two built in users by default. You can add additional users by using the 'Sign Up' page and you can change a user's password under the Settings once logged in.
| Username | Password |
|---|---|
| admin@admin.com | admin |
| test@test.com | test |
This repo is a work in progress - IT IS NOT PRODUCTION READY. We don't expect you to use the entire thing as is, but we're hoping that you'll at least find parts of it useful for your own development.
This is subject to change, but the items that we plan to work on next are the following:
- Fix broken tests
- Make rules engine pluggable
- Add socket.io authentication
Publish websocket events that the rules engine listens for instead of calling directly- Auto register beacons when they are first seen (like we do for agents)
- Make uuids case and dash insensitive (currently only supports uuids in all lowercase without dashs)
- Pull list of audio file choices and urls from S3 bucket in order to provide list of files to play dynamically (currently the UI auido file list is hardcoded)
ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)" //Installs homebrew package manager
sudo brew update
sudo brew install node
npm install grunt-cli -g
npm install bower -g
//Installs all of the NodeJS Courier packages.
npm install
bower install
Install and start MongoDb
brew install mongodb
//Add to start up
ln -sfv /usr/local/opt/mongodb/*.plist ~/Library/LaunchAgents
launchctl load ~/Library/LaunchAgents/homebrew.mxcl.mongodb.plist
//Or just launch once
mongod --dbpath=/usr/local/var/mongodb
Run grunt serve to get it running:
grunt serve
Run Mocha Tests
grunt mochaTest
Warning: We know that some of these are broken. We are working on it.
Javascript developers, don't laugh but we have Java developers working on this code and they like to use IntelliJ. So be it. Feel free to use your favorite Javascript editor - Sublime, Atom, etc. This is more for our own reference, but perhaps you'll find it useful.
Instructions are posted in the wiki https://github.com/makeandbuild/Courier/wiki/IntelliJ-Setup