ubirch / ubirch-avatar-service   0.4.2

Apache License 2.0 GitHub

ubirch device-configuration and -dataflow service

Scala versions: 2.11


ubirch device-configuration and -dataflow service

Run the service

by executing:

sbt server/run

you can also enter the sbt shell and enter:

project server

General Information

ubirch Avatar Service is responsible for:

  • offering ubirch IoT devices an endpoint to sync their state
  • processing incoming raw data from ubirch IoT devices ** validating signatures ** transforming raw data
  • offering CRUD API to manage ubirch IoT Devices
  • managing device states using Amazon AWS IoT
  • publishing processed data for further processing (AWS SQS)

Release History

this content has been moved to a separate file: docs/release-history.md

SBT Dependency Graphs

To browse the dependency graph, this project uses the plugin sbt-dependency-graph (https://github.com/jrudolph/sbt-dependency-graph)

To browse e.g. the dependencyGraph for each module use the command 'dependencyBrowseTree' in the sbt shell.

Scala Dependencies

this content has been moved to a separate file: docs/release-history.md

REST Methods

this content has been moved to a separate file: docs/rest-methods.md


The ubirch avatar service has several external dependencies:

  • ElasticSearch

Those are configured via environment variables.


In order to talk to AWS SQS the service needs two SQS targets:


Those queues need authentication with AWS credentials. These are passed via



Avatar service is using ElasticSearch for logging and device management. It needs a specific ES version and access to Port 9200 (HTTP) and Port 93000 (TCP)


Debug Output

Since ubirch avatar service is using ElastiSearch for logging it can be hard to figure out what's not working if the connection to ES can't be established. If you set


as environment variable then the logging is send to STDOUT.


AWS Console Account

Login on https://console.aws.amazon.com/console/home with your AWS account. Without an account or not having logged AWS connections might not work.


On MacOS you can install the aws-cli tool through brew:

brew install awscli

To configure it then run:

aws configure

The default region should be us-east-1 while the output format can remain None since it's not relevant yet.

AWS Configuration

The AvatarService opens a connection to AWS which depends on the following environment variables:

export AWS_ACCESS_KEY_ID=foo

Deployment Notes


The service requires the mappings defined in ElasticsearchMappings. They are automatically created during server boot if they don't exist.

Automated Tests

To run the tests, first run the docker-compose file in local-test-setup/run-unit-tests and then start the tests.

cd local-test-setup/run-unit-tests
docker-compose up 
cd ../..
sbt test

Import Trackle Data

  1. Prepare User

    The test data generation includes the generation of test data and a device. This means we still need a user which you'll have to create/register manually by logging in on the AdminUI of the remote environment. Please remember the token resulting from the registration or login.

  2. Prepare Data Import

    # user token from registration or login
    export AVATAR_USER_TOKEN=token-12345678
    # (optional) base url of the remote environment's avatar-service (defaults to http://localhost:8080)
    export AVATAR_BASE_URL=https://avatar.myserver.com:8080
  3. Run Data Import

You can also run dev-scripts/importTrackle.sh $AVATAR_USER_TOKEN.

./sbt "cmdtools/runMain com.ubirch.avatar.cmd.ImportTrackle"