Status	Coverage	Docs	Site Release	Style
		TBA	2024.05.xx

---

frb-voe : An FRB Virtual Observatory Event Service

frb-voe is a telescope-agnostic server for publishing, broadcasting, and recording Virtual Observatory Events (VOEvents) for detections of Fast Radio Bursts (FRBs). Telescopes and observatories that are actively detecting or following up FRBs can establish a subscription-based FRB VOEvent service using frb-voe. The core functionality of the code base is the following tasks:

• Publish VOEvents that follow an extension to the FRB VOEvent Standard originally prescribed in Petroff et al. 2017 using a Comet broker and/or an SMTP email server.
• Maintain and interact with a Mongo Database of VOEvent metadata and subscribers information.
• Submit FRBs to the Transient Name Server (TNS).

Installation

Dependencies Installation

The following are instructions for installing the frb-voe package and running the TNS service.

First, cd into your preferred path /my/path and clone the repository.

git clone git@github.com:CHIMEFRB/voe.git

Now, move into the repo:

cd voe

And build the docker container and initialize the servers and database. If you do not have docker installed on your system, instructions can be found here: https://docs.docker.com/get-docker/.

docker compose build

Note: MongoDB is set to run at port 27017 by default. Ensure nothing is running at this port, or, choose another port by changing the SANIC_MONGODB_PORT variable in the docker-compose.yaml file (and the corresponding ports in the mongo configuration).

Getting Started

Environment Variables

Certain aspects of the service (such as SMTP servers and interactions with the TNS) require sensitive information such as passwords and API keys. To use these services, it is recommended that you pass these secrets as environment variables. These must be added to your bash profile with the following naming convention.

• FRB_VOE_EMAIL_ADDRESS
• FRB_VOE_EMAIL_PASSWORD
• FRB_VOE_TNS_API_KEY
• FRB_VOE_TNS_BOT_NAME
• FRB_VOE_TNS_BOT_ID

To obtain a TNS API key, bot name, and bot ID, proceed to the next section.

Registering on the TNS

The TNS is the official IAU-recognized distributor and maintainer of the naming scheme for FRBs. All programmatic requests to the TNS require authentication. This in turn requires registration on the TNS web portal. To complete the registration process and obtain required authorization, follow these steps:

1. Request a User Account here. If you had additional team members who will manage your TNS data, they should also create a User Account.
2. Log in here.
3. Edit your TNS Group members here.
4. Add a TNS bot here. This is required in order to obtain the credentials that are needed for making programmatic requests to the TNS via the API that is embedded in frb-voe.
5. Once your TNS bot has been created, it will appear in the table on this page. In the rightmost column you can click edit to view or change its properties. In particular, the Edit Bot page allows one to create a new API key for the bot at any time.
6. From the Edit Bot page, one can obtain values for the environment variables that are required to use the TNS functionality of frb-voe.
   • FRB_VOE_TNS_API_KEY from the API alphanumeric key value.
   • FRB_VOE_TNS_BOT_ID from the "tns_id" key in the User-Agent specification.
   • FRB_VOE_TNS_BOT_NAME from the "name" key in the User-Agent specification.

frb-voe Client User Interface (CLI) Usage

Once the frb-voe backend is started, a dedicated CLI can be used for all interactions software.

Interacting with the frb-voe Server

poetry run frbvoe voe [COMMAND] [OPTIONS]

Send a VOEvent

poetry run frbvoe voe send --help

Interact with the Subscriber Database

poetry run frbvoe subscriber [COMMAND] [OPTIONS]

Adding a subscriber

poetry run frbvoe subscriber add --help

Interact with the TNS

poetry run frbvoe tns [COMMAND] [OPTIONS]

Submit an FRB

When you have the event number of a FRB Candidate that needs to be submitted to the TNS, use the following command to acquire the TNS name.

poetry run frbvoe tns submit --help

The help dialogue will explain what options are required and what data is needed from the user. These include:

• event number
• proprietary period length (in years)

Optionally, one can practice the submission by setting the --sandbox flag in the call signature.