Mayu: Rack app to locate employees in an office by Wi-Fi MAC address and WLC association data

UNDER DEVELOPMENT, just API works

Add this line to your application's Gemfile:

gem 'mayu'

And then execute:

$ bundle

Or install it yourself as:

$ gem install mayu

1. Associaton collector: Collecting pair of MAC address => AP name
2. User collector: Collecting pair of MAC address => user information
3. Frontend: Web API and Frontend

This gem includes (1) for Cisco WLC and (3). About (2), you have to write your own script to generate JSON.

All data is stored in Amazon S3.

bundle exec mayu-association-collector

• --interval (default: 60, env: $MAYU_ASSOC_INTERVAL): Interval in seconds to run updating.
• --ttl (default: 300, env: $MAYU_ASSOC_TTL): seconds to remove disappeared devices from list.
• --wlc (required, env: $MAYU_ASSOC_WLC): Address of WLC for SNMP communication
• --community (required, env: $MAYU_ASSOC_WLC_COMMUNITY): SNMP community of WLC
• --use-ap-mac-for-key (env: $MAYU_ASSOC_AP_MAC_KEY): Use MAC address of AP for identifying APs, instead of its name
• --use-wlc-user (env: $MAYU_ASSOC_USE_WLC_USER): Use username assigned by WLC for identifying user
• Choose either:
  • File:
    • --output (required, env: $MAYU_ASSOC_FILE)
  • S3:
    • --s3-region (required, env: $MAYU_ASSOC_S3_REGION)
    • --s3-bucket (required, env: $MAYU_ASSOC_S3_BUCKET)
    • --s3-key (required, env: $MAYU_ASSOC_S3_KEY)

Write your own logic to collect your employees' device MAC addresses.

See Internal and place a properly formatted JSON file in S3.

bundle exec rackup

Run as a Rack app. Refer the bundled config.ru

The bundled config.ru accepts:

• $MAYU_WEB_RELOAD_INTERVAL (default: 60)
• $MAYU_ASSOC_S3_REGION
• $MAYU_ASSOC_S3_BUCKET
• $MAYU_ASSOC_S3_KEY
• $MAYU_USER_S3_REGION
• $MAYU_USER_S3_BUCKET
• $MAYU_USER_S3_KEY

Also, this app needs a list of APs for displaying a map.

• $MAYU_AP_S3_REGION
• $MAYU_AP_S3_BUCKET
• $MAYU_AP_S3_KEY

This JSON file should be formatted with a format in Internal

• All datetimes in a JSON should be formatted in ISO8601.
• MAC addresses should be formatted like 00:00:5e:00:53:a1 (hex, : separated, all lower case)

{
  "associations": [
    {
      "mac": "DEVICE_MAC",
      "user_key": "USER",
      "ap_key": "AP_KEY",
      "updated_at": "UPDATED_AT",
      "appeared_at": "APPEARED_AT",
      "disappeared_at": "DISAPPEARED_AT"
    }
  ]
}

• DEVICE_MAC: MAC address
• USER (optional): User key, if a user is determinable by an association. Otherwise user will be looked up from device MAC.
• AP_KEY: AP key (name, MAC address or anything. Key should be consistent among all other JSON files)
• UPDATED_AT: Time that this association updated.
• APPEARED_AT: Time that this association appeared.
• DISAPPEARED_AT (optional): Time that this association disappeared.

{
  "users": [
    {
      "key": "KEY",
      "name": "NAME",
      "aliases": ["ALIAS"],
      "gravatar_email": "GRAVATAR_EMAIL"
    }
  ],
  "devices": [
    {
      "user_key": "USER_KEY",
      "key": "DEVICE_KEY",
      "mac": "DEVICE_MAC",
      "kind": "DEVICE_KIND"
    }
  ]
}

• KEY: Key (should be consistent among all other JSONs)
• NAME: Name
• ALIAS (optional): Alias (username, email, etc)
• GRAVATAR_EMAIL (optional): Gravatar email
• DEVICE_MAC: Device Wi-Fi MAC address that user owns.
• DEVICE_KIND (default: other): Kind of device (pc, phone, tablet, other)

{
  "maps": {
    "MAP_KEY": {
      "name": "MAP_NAME",
      "url": "MAP_IMAGE_URL",
      "fg_color": "HI_COLOR",
      "bg_color": "HI_COLOR",
      "highlight_color": "HI_COLOR"
    }
  },
  "aps": {
    "AP_KEY": {
      "name": "AP_NAME",
      "description": "AP_DESCRIPTION",
      "map_key": "AP_MAP_KEY",
      "map_x": "AP_MAP_X",
      "map_y": "AP_MAP_Y"
    }
  }
}

• MAP_KEY: Key of map (should be consistent among other JSON files)
• MAP_NAME: Name of map (Floor name, etc)
• MAP_IMAGE_URL: Image URL
• MAP_HI_COLOR: Color for highlighting
• AP_KEY: AP key
• AP_NAME: Name of AP
• AP_DESCRIPTION: Description of AP (location information for human, etc)
• AP_MAP_KEY: Map corresponding for AP
• AP_MAP_X: X position of AP in map
• AP_MAP_Y: Y position of AP in map

• user
  • devices
    • association
• association
  • ap
  • device
• map
  • aps
    • associations

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/sorah/mayu.

The gem is available as open source under the terms of the MIT License.