-
Notifications
You must be signed in to change notification settings - Fork 52
Administration guide
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:
- feeds - one live feed for each hydrophone location
- detections - a new detection is created when a human listener indicates they hear something interesting
- candidates - a new candidate is defined when a new detection occurs more than 3 min after a previous candidate’s last detection
- users - users are initially network admins and moderators, but may have other roles (e.g. hydrophone host organization)
- subscribers - are entities who would like to subscribe to some type of notification
- subscriptions - options for subscribers include emails upon 2 types of events: new human detection, and/or candidate confirmed by a moderator
- notifications - communication events with subscribers via subscriptions
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 **
** Example data Schema view **
Here are some handy links for learning more, and then some example queries:
- GraphiQL on Github (pronounced "Graphical", i.e. /ˈɡrafək(ə)l/ )
- GraphiQL tutorial by ScienceLogic
query {
feeds {
name
slug
}
}
query {
candidates {
count
}
}
Returns 3989
on 12/1/2023; 4373
on 2/10/24.
query {
detections {
count
}
}
Returns 7062
on 12/1/2023; 7655
on 2/10/24.
{
detections (limit: 5, filter: {category: {eq: WHALE}} ) {
results {
timestamp
description
feed {
slug
}
}
}
}
Returns this on 2/10/24 at 00:30 Pacific:
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):
For example, the feeds
table as of 5/5/2022 (with three hydrophone locations in Washington State) looks like this:
Here's a description of the 7 fields in the feeds
table:
-
id
= a unique index associated with this row in the table -
name
= A human readable description of the location. In v2 this text string is used to populate the drop-down feed list. -
node_name
= a string with formatdevice_location_name
that uniquely identifies the location within the S3 buckets used to store audio data from this location. Note thatrpi
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 theorcasite
S3 bucket used within each feed page of the v2 UI. -
slug
= a string used at the end oflive.orcasound.net
orbeta.orcasound.net
to complete the URL of a given feed page, e.g.https://live.orcasound.net/orcasound-lab
-
inserted_at
= a timestamp when the row was created -
updated_at
= a timestamp when the row was updated most recently -
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 = WKTPOINT(-122.33393605795372 47.86497296593844)
into this handy WKB-point converter site
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
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
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.
- Review reports from Orcasound listeners (while authenticated as a moderator)
- Listen to the candidate event until you are 100% sure the listener heard a whale.
- select the NOTIFY SUBSCRIBERS button (in gray on right side of the screenshot below), if all these conditions are met:
- the signal to noise ratio is currently good enough for an exciting and compelling live-listening session;
- 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,
- 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)
- 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:
- Select the
SUBMIT
button. - 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