Page tree
Skip to end of metadata
Go to start of metadata

BigSense

BigSense needs to connect to a database for its storage. Currently the following databases are supported:

  • MySQL 5+
  • Postgres 9.2+ (postgis extension required)
  • Microsoft SQL 2012+

Example configuration files can be found in /etc/bigsense/examples. Copy the appropriate file for your database type into /etc/bigsense/bigsense.conf. Here's an example for a Postgres configuration file:

dbms=pgsql
dbHostname=localhost
dbPort=3456
dbDatabase=bigsense
dbUser=db_bigsense
dbPass=bigsense
dboUser=db_bigsense_ddl
dboPass=bigsenseDDL
securityManager=Disabled
httpPort=8181
server=tomcat
  • dbms can be either pgsql, mysql or mssql for Postgres, MySQL and Microsoft SQL respectively
  • dbHostname, dbPort and dbDatabase are database connection parameters
  • dbUser/dbPass and dboUser/dboPass specify the two database users
    • The DBO user can update the schema and is only used upon startup of BigSense
    • The non-DBO user is used for all further connections when reading from/writing to the database
  • securityManager can be used to verify all incoming sensor data. Currently can be set to Disabled or Signature. (TODO: link to security section)
  • httpPort the port the web service will run on
  • server can be either jetty or tomcat

Database

Next, a database needs to be created. The initial schema can be created using the bigsense --ddl command. It will build this initial schema based off the information in /etc/bigsense/bigsense.conf

sudo /usr/bin/bigsense --ddl > initial.sql

You'll need to copy and run this schema on your database server. It creates both the dbUser and dboUser, along with the database itself and assigns all relevant passwords and permissions. The way you load this schema into your database will vary depending on your setup, but an example on postgres would be the following:

sudo -u postgres psql < initial.sql 

You may have access control restrictions for your database server

  • For MySQL, the DDL generator will attempt to guess the BigSense servers hostname. Check the SQL file to ensure it put in the correct host
  • For PostgreSQL, access control is typically located in /etc/postgresql/<version>/main/pg_hba.conf
  • For MicrosoftSQL, be sure to enable the relevant firewall rules

PostgreSQL doesn't come with geospacial support. You must install the postgis extension or else the schema will fail to properly load

Finally, restart the BigSense service on the server you installed it to.

service bigsense restart

You can monitor it starting up, and view any diagnostic information, by viewing the log file located at /var/log/bigsense/bigsense.log.

LtSense

The configuration for ltsense is located at /etc/ltsense/ltsense.conf. The following is an example configuration file that sends sensor data to a BigSense instance running at example.com at a 15 second interval using two fake/virtual sensors which generate random data:

[General]
sample_rate = 15
[Data]
  [[primary]]
    type = sense.xml
      [[[Identifier]]]
        type = name
        id = ExampleRelay01
      [[[Location]]]]
        type = gps
[Transport]
  [[http]]
    type = http
    url = https://example.com/Sensor.agra.xml
    pause_rate = 1.0
    timeout = 10.0
      [[[Queue]]]
        type = memory
      [[[Security]]]
        type = none
[Handlers]
  [[virtual]]
    type = virtual
    sensors = $temp1,$temp2
[Sensors]
  [[temp1]]
    type = virtual/temp
    id = VRTEMP01
    units = C
    rangeMin = 1
    rangeMax = 25
  [[temp2]]
    type = virtual/temp
    id = VRTEMP02
    units = C
    rangeMin = 1
    rangeMax = 25

Configuration Sections

  • General
    • sample_rate = the rate at which sensor handlers are queried in seconds
  • Data
    • [name] - Multiple data types can be defined, each with a unique name. All data types are sent to all transport types.
    • type - data format (currently only sense.xml is supported)
    • Identifier
      • type - Indicates how the relay is identified. Possible values are name, mac and uuid
        • mac - Uses network adapter's mac address for identifier. Valid attribute is adapter, defaults to eth0
        • example:

          [[[Identifier]]]
            type = mac
            adapter = eth2
        • name - Uses a static name defined in the configuration file
        • example:

          [[[Identifier]]]
            type = name
            id = MyRelay01
        • uuid - Uses a generated UUID. Requiresid_file attribute
        • example:

        • [[[Identifier]]]
            type = uuid
            id_file = /var/lib/ltsense/uuid
    • Location (section is optional. If omitted, no location data will be transmitted)
      • type - Possible values are virtual and gps. Virtual uses static values (shown below) where as gps will attempt to connect to the locally running gpsd instance.
      • longitude (virtual only)
      • latitude (virtual only)
      • altitude (virtual only)
      • speed (virtual only)
      • climb (virtual only)
      • track (virtual only)
      • longitude_error (virtual only)
      • latitude_error (virtual only)
      • altitude_error (virtual only)
      • speed_error (virtual only)
      • climb_error (virtual only)
      • track_error (virtual only)
  • Transport
    • [name] - Multiple transport types can be defined, each with a unique name. All data types are sent to all transport types.
      • type - Currently only http is supported (Even if using SSL/TLS, this should still be http. https can be specified in the URL)
      • url - Service endpoint URL
      • pause_rate - Minimum amount of time in seconds to wait between sending sensor data pacakges (default: 0.10)
      • timeout - Amount of time in seconds to wait after sensor data failed to send (data package is placed back on the queue, default: 10.0)
      • Queue
        • type - Valid types are memory and sqlite.
          • Memory based queues are reset when the process ends with any packages in the queue discarded.
          • example:

            [[[Queue]]]
              type = memory
            
          • Sqlite queues store packages across restarts in a file.
          • example:

            [[[Queue]]]
              type = sqlite
              sql_file = /var/lib/ltsense/queue.sqlite 
      • Security
        • type - Valid types are none, rsa and m2
          • For m2 (pypi - M2Crypto) and rsa (pypi - rsa), the data_dir, key_file and key_size must be specified. If a key does not exist, LtSense will attempt to create one in the data_dir with the name specified in key_file.
          • example:

            [[[Security]]]
              type = rsa
              data_dir = /var/lib/ltsense
              key_file = ltsense.pem
              key_size = 2048 
  • Handlers
    • [name] - Multiple handlers can be specified with unique names. Each handler will query its sensors and return data that will be encoded by formats listed in the Data section before being passed to the services listed in the Transport section
      • type - Valid types are virtual, 1wire
        • Virtual sensors are fake sensors used in testing that report random data. The handler takes a list of sensors that must be defined in the Sensor section
        • 1wire sensors can specify a device (default is u for USB. This can also be a path to a serial interface, e.g. /dev/ttyUSB0, or the address/port of a owserver, e.g. localhost:1234)
        • example:

          [Handlers]
            [[virtual]]
              type = virtual
              sensors = $temp1,$temp2

          sensors must be a list. If you only have one sense, leave a trailing coma:

          sensors = $virtual1,

        • 1/Wire USB sensors are auto detected
        • example:

          [Handlers]
            [[virtual]]
              type = 1wire
              device = u

          You must have the python-ow (1-Wire File System) package installed to use 1wire sensors directly over USB with LtSense.

          If you want to connect to an instance of an owserver (1-Wire File System Server), you should have python-ownet installed.

          The LtSense package comes with a udev rule so that the ltsense user should automatically get permission for 1-wire USB dongles. This rule may need to be adjusted if you have permission errors.

  • Sensors

    • [name] - Unique name for a virtual sensor that is referenced in the Handler section. 

      • type - The two virtual sensor types are virtual/temp and virtual/image

        • Virtual temperature sensors take a range from which to generate a number from. They must specify id, units, rangeMin and rangeMax

        • example:

          [Sensors]
            [[temp1]]
              type = virtual/temp
              id = VRTEMP01
              units = C
              rangeMin = 1
              rangeMax = 25
            [[temp2]]
              type = virtual/temp
              id = VRTEMP02
              units = C
              rangeMin = 1
              rangeMax = 25
        • Virtual Image sensors transmit the same image continuously using the image_file attribute
        • example:

          [Sensors]
            [[photo1]]
              type = virtual/image
              image_file = /var/lib/ltsense/test.jpg

After you've configured LtSense, restart the LtSense service.

# Upstart

service ltsense restart

# SystemD

systemctl restart ltsense.service

# SystemV

/etc/init.d/ltsense restart

You can monitor it starting up, and view any diagnostic information, by viewing the log file located at /var/log/ltsense/ltsense.log.

 

 

 

 

 

  • No labels