Quickstart

Install the snews_pt package with its dependancies following the installation guide. The snews_pt package allows you to interact with the SNEWS2.0 server.

User can subscribe to the alert messages and publish their observation messages to the server.
This is done using the scimma’s hopskotch client. For more on hopskotch and the available topics, see here.

First you need to generate credentials and join the snews group.

1) Hop-Credentials

Go to https://my.hop.scimma.org/hopauth and generate account and request access to the SNEWS user group. See this page for help.

1.1) Setup hop-client

hop-client should already be installed as a requirement for snews_pt confirm your installation by checking the version

hop --version

if this successfully returns you the version then you have the package. (Notice snews_pt might require a specific version)

If not install the hop-client via pip or conda

pip install -U hop-client
----------------------- OR
conda install -c conda-forge hop-client

Once you are on hopauth page login with to your account and add credentials (the plus icon on the top left) and store your username and password.

On your local machine, you need to add this credentials to your hop-client. Checkout hop auth --help on your terminal for instructions. You can add your username-password using hop auth add. Once it is done, your local computer knows about your credentials, and it can interact with the topics that credential has access to.

1.2) Request permissions

You now have a hop account and newly created credentials, however, you still do not have access to SNEWS topics. For that, you are first required to be added to the SNEWS User group by one of the admins. For that please contact us on SNEWS slack, on the implementation channel. Different groups and the topics are detailed in hopskotch page

Once you have access to certain SNEWS user group, you can add permissions to the following topics;
(These topics might change during the development)

  • snews.alert

  • snews.alert-firedrill

  • snews.experiments

  • snews.experiments-firedrill

  • snews.connection-testing

Required Permissions

“alert” topics are to be subscribed and “experiments” topics are to be published. snews_pt uses these topics to interact with the server.
The snews_pt package includes the default observation and alert topics for both firedrill and non-firedrill cases. However, different topics can also be specified. See the next section.

2) Configurations

The package comes with a default configuration file that contains some useful information. This file can be found under auxiliary/test-config.env and looks like this;

DETECTOR_NAME='TEST'
HAS_NAME_CHANGED='0'
...
HOP_BROKER="kafka.scimma.org"

OBSERVATION_TOPIC="kafka://${HOP_BROKER}/snews.experiments-test"
ALERT_TOPIC="kafka://${HOP_BROKER}/snews.alert-test"
PRODUCTION_TOPIC=""

FIREDRILL_OBSERVATION_TOPIC="kafka://${HOP_BROKER}/snews.experiments-firedrill"
FIREDRILL_ALERT_TOPIC="kafka://${HOP_BROKER}/snews.alert-firedrill"
CONNECTION_TEST_TOPIC="kafka://${HOP_BROKER}/snews.connection-testing"

The file can fetch the topics and can also be aware of the detector’s name thus reducing the manual tasks. As long as you have “TEST” as your detector name, software will raise a warning and remind you to change it.

Once you install the snews_pt you can set your experiments name either by changing this file, or running the following command on a python API;

import snews_pt
snews_pt.snews_pt_utils.set_name()

Here set_name() can take the name as a string, but if executed without an argument, it will display the accepted detector names and request an input based on the index of your detector.

Or you can also set your detectors name using the terminal;

snews_pt set-name

You only need to this once. As long as you do not set a valid name, snews_pt will keep complaining. Once the name is set, the HAS_NAME_CHANGED argument will be changed to 1 to indicate the program not to ask again.

Warning: If you run tests, each time you use a different detector name, this file will change. Be aware that unless the detector name is not passed explicitly it will fetch it from this file.

Similarly, if you wish to use a different topic as the “alert topic” or “observation topic” instead of the default ones. You can change these entries in the environment file.

Once you set these, you are ready to publish your observations and subscribe to alerts!

3) Interact with the Server

3.1) Test your connection

snews_pt has a tool to test your connection, if the topic that you are trying to test is running on the server it should see your test message and send back a confirmation to you. Simply run the following on your terminal,

snews_pt test-connection --no-firedrill

Sometimes the “firedrill” broker is running, if that is the case you can omit --no-firedrill flag.

test connection

3.2) Subscribe and Publish

Here is a quick start for subscribing to alert messages and sending your observation messages using the command line interface. For Python API and more see the table of contents below.

snews_pt subscribe

snews_pt publish my_json_message.json

For more information, see the respective pages for publish and subscribe.

4) Further Use

You can find further documentation regarding the use of snews_pt in index. We provide both a python API and a command line access to most of snews_pt functionalities.