Skip to content

Administration guide

Jump to bottom
Scott Veirs edited this page Feb 27, 2024 · 25 revisions

How-to guides for Orcasite administration

Orcasite is deployed (as of late 2018) via the Heroku Git (use heroku CLI = command line interface). Each Heroku app (for live, beta, and dev.orcasound.net) has a distinct Postgres database and host URL.

The databases have an evolving number of tables. As of September 2023 they include:

  1. feeds - one live feed for each hydrophone location
  2. detections - a new detection is created when a human listener indicates they hear something interesting
  3. candidates - a new candidate is defined when a new detection occurs more than 3 min after a previous candidate’s last detection
  4. users - users are initially network admins and moderators, but may have other roles (e.g. hydrophone host organization)
  5. subscribers - are entities who would like to subscribe to some type of notification
  6. subscriptions - options for subscribers include emails upon 2 types of events: new human detection, and/or candidate confirmed by a moderator
  7. notifications - communication events with subscribers via subscriptions

How-to: play in the "Graphical" playground!

As of orcasite UI version 3, a GraphiQL playground has been implemented at live.orcasound.net/graphiql. (Thanks, Skander!) Below are a couple screenshots of the playground and current data schemes, as well as some sample queries.

** The playground in v3 **

Screenshot 2023-12-01 at 3 53 23 PM

** Example data Schema view **

graphiql-schema

Here are some handy links for learning more, and then some example queries:

Example GraphiQL queries

View production feeds

query {
  feeds {
    name
    slug
  }
}

Count current candidates

query {
  candidates {
    count
  }
}

Returns 3989 on 12/1/2023; 4373 on 2/10/24.

Count current detections

query {
  detections {
    count
  }
}

Returns 7062 on 12/1/2023; 7655 on 2/10/24.

Show 5 most-recent detections in the WHALE category

{
  detections (limit: 5, filter: {category: {eq: WHALE}} ) {
    results {
      timestamp
      description
      feed {
        slug
      }
    }
  } 
}

Returns this on 2/10/24 at 00:30 Pacific:

Screenshot 2024-02-10 at 12 30 57 AM

How-to: add a node (in a live network)

Overview

Each hydrophone location is a node in the physical network. Within a deployed version of orcasite, the node represented by a row in the feeds table. That table is part of this Postgres database schema (as of 2022):

Orcasite-Postgres-scheme

For example, the feeds table as of 5/5/2022 (with three hydrophone locations in Washington State) looks like this:

Orcasite-Postgres-feed-dump

Here's a description of the 7 fields in the feeds table:

  1. id = a unique index associated with this row in the table
  2. name = A human readable description of the location. In v2 this text string is used to populate the drop-down feed list.
  3. node_name = a string with format device_location_name that uniquely identifies the location within the S3 buckets used to store audio data from this location. Note that rpi stands for Raspberry Pi, the device type currently running at each Orcasound location. Sometimes node_name is also used to organize other content for the node, like text and images in the orcasite S3 bucket used within each feed page of the v2 UI.
  4. slug = a string used at the end of live.orcasound.net or beta.orcasound.net to complete the URL of a given feed page, e.g. https://live.orcasound.net/orcasound-lab
  5. inserted_at = a timestamp when the row was created
  6. updated_at = a timestamp when the row was updated most recently
  7. location_point = the latitude and longitude of the node location, encoded in Well Known Binary format

So, as an example, to add a new node at Sunset Bay (between Mukilteo and Edmonds in Puget Sound), you will need the following fields and values:

  • name = Sunset Bay
  • node_name = rpi_sunset_bay
  • slug = sunset-bay
  • location_point = 010100000073f757355f955ec09b50246fb7ee4740 (based entering the Well Known Text = WKT POINT(-122.33393605795372 47.86497296593844) into this handy WKB-point converter site

Current feed table values

Last update 3/17/2023 (via this Heroku Postgres data clip)

1
Orcasound Lab (Haro Strait)
rpi_orcasound_lab
orcasound-lab
2018-10-04 18:00:25.226009
2018-10-06 05:40:00.03497
0101000020E61000000B410E4A98CD4740E57E87A240955EC0

2
Bush Point
rpi_bush_point
bush-point
2018-10-10 22:59:52.629935
2018-10-11 00:22:33.49018
0101000020E61000003411363CBD1A48405A2A6F4738975EC0

35
Port Townsend
rpi_port_townsend
port-townsend
2019-07-11 21:31:02
2019-07-11 21:31:02
0101000020E610000099D4D006601148404EB857E6ADB05EC0

36
Sunset Bay
rpi_sunset_bay
sunset-bay
2022-10-07 18:51:17
2022-10-07 18:51:17
0101000020E61000009B50246FB7EE474073F757355F955EC0

The translated latitudes and longitudes for each feed/node are:

  • 47.606210 -122.332070 | Orcasound Lab
  • 48.208900 -122.362810 | Bush Point
  • 48.135743 -122.760614 | Port Townsend
  • 47.864973 -122.333936 | Sunset Bay

Lat/Lon pairs for new nodes to be added to the dynamic map in v3 of the live-listening app:

  • 48.591294 -123.058779 | North San Juan Channel | rpi_north_sjc
  • 47.34922, -122.32512 | MaST Center | rpi_mast_center
  • 47.388383, -122.37267 | Point Robinson | rpi_point_robinson

Adding a new feed manually

Currently (May 2022), the only way to add a new feed is by manually connecting to the running app. First, you need to have installed the Heroku CLI. After logging in with the CLI, you can connect to the Elixir interactive shell (IEx) by running:

heroku run POOL_SIZE=2 iex -S mix -a orcasite

In this case we're connecting directly to the production app (orcasite) but we could easily connect to another app (e.g. orcasite-beta):

heroku run POOL_SIZE=2 iex -S mix -a orcasite-beta

Once IEx is up and running you should see something like this

image

From here, we'll use Ecto to directly make changes to the database (be careful!). Entering the following will create a new entry in the database for the Sunset Bay hydrophone.

alias Orcasite.Repo
alias Orcasite.Radio.Feed

feed = %Feed{
  location_point: Geo.WKT.decode!("SRID=4326;POINT(-122.33393605795372 47.86497296593844)"),
  name: "Sunset Bay",
  node_name: "rpi_sunset_bay",
  slug: "sunset-bay"
}
Repo.insert!(feed)

We're done! The new feed should show up in the database and on the site. Don't forget to update S3 bucket with the HTML content and images, and of course, make sure the node is streaming to the streaming-orcasound-net bucket.

How-to: send an email to subscribers (as of 2023, post-MailChimp)

  1. Review reports from Orcasound listeners (while authenticated as a moderator)
  2. Listen to the candidate event until you are 100% sure the listener heard a whale.
  3. select the NOTIFY SUBSCRIBERS button (in gray on right side of the screenshot below), if all these conditions are met:
  1. the signal to noise ratio is currently good enough for an exciting and compelling live-listening session;
  2. you believe that the animal/group is likely to continue for at least 5-10 more minutes (e.g. the signals are not rapidly fading out); and,
  3. you expect noise levels to not increase rapidly during the event(e.g. you've checked for approaching vessels via [vesseltraffic.com](https://vesseltraffic.com)
Screenshot 2024-02-27 at 1 15 54 PM
  1. In the modal, add some text that will customize the top header within the email template. For example, type Southern Resident Killer Whale are currently being heard near the Sunset Bay hydrophones in north Puget Sound (between Edmonds and Mukilteo)! and you'll get this type of result:
Screenshot 2024-02-27 at 2 10 56 PM
  1. Select the SUBMIT button.
  2. If you want to cancel the sending of your notification at any point in the throttled process, select the CANCEL button.

Associated resources:

Current template (Feb 2024)

One mjml editor: (https://mjml.io/try-it-live) and some other options as well (desktop app, vs code extension).

Another mjml wysiwyg editor: https://grapesjs.com/demo-mjml.html

Clone this wiki locally