This is a desription of how your transient events from your mission, telescope, instrument or project
can become part of the GCN/TAN system -- can become a new Notice type.
This will get you started on how it might be done, but I also encourage you to call (301-286-3106) or
email me (scott@milkyway.gsfc.nasa.ogv) because there are many variations and details
that need to be worked out before you make a choice on which way you want to go.
We actively invite missions/instruments/telescopes/projects to contribute your transient detections to the GCN/TAN system.
We encourage all multi-messenger (particle, EM (radio, IR, optical, UV, X-/Gamma-rays), and gravitational waves).
This page tells perspective contributors of notices to the GCN what all is needed and how to go about doing it.
This includes the mechanics of contributing, how to set it up, and the details there in.
Things to consider are:
* What is the category of the transient events (GRB? SGR? other transients? gamma-/xray-/optical-/radio-/particle-/gw-based?).
* Is there a single message per event, or is there a sequence of messages for each event (initial, update, final)?
* Will there be retractions?
* Is it just a timestamp that something happened, or is there a location, or lightcurves, images, spectra, etc?
* What is the time latency from when the event happened to when the message is available (sec, min, hrs, days)?
* What method will be used to get them from your end to the GCN computer (socket? email? other?).
* Will these be be available to the public, or only to a private subnet?
There are 4 basic methods for getting information (pre-Notice messages) into GCN:
1) BINARY-SOCKET METHOD: a TCP/IP socket connection is made between your computer
and the GCN computer. You send packets of known/agreed-to format and content to GCN;
GCN takes it and turns it into all the available formats for distribution.
2) VOEVENT METHOD: also a socket connection with a VOEvent format (instead of the binary packet format).
3) EMAIL METHOD: your computer sends email (of an agreed to format) to a GCN account (vxw@capella2.gsfc.nasa.gov)
and a procmailrc rule drops the email into an import directory which GCN checks that dir
and reads in the file (parses it, puts it into all the standard GCN formats, and distributes it).
4) VOEVENT-FORMAT EMAIL METHOD: your computer sends an email to GCN where the body of the email is a voevent.
(The same seqeunce of activities as for '3' happens for '4'.)
5) OTHER METHODS: There are two other methods for ingesting (see table below): Raw spacecraft telemetry (used only by Swift), and
a UDP socket protocol that the INTEGRAL project chose and GCN accomodated. Those are special circumstances.
The first two methods (socket-based) are used for cases where high volume and/or low latency are present.
The next two methods (3 & 4) (email-based) are used for low volume (<~1/minute) and long latency (>~50 sec).
The figure below shows the basic architecture (and flow) of missions/projects producing messages (far left),
sending them to 'receiver' programs on the GCN computer, and then to the gcnmain program which distributes them to the world.
1) BINARY-SOCKET EXAMPLE: Examples of the content of 160-byte binary packets can be found in socket packet document.
But keep in mind that these are the GCN-outgoing formats; the incoming message formats are similar, but do not have to be identical.
Here is an example of the 40 4-byte interger fields in the binary packet sent to GCN.
(Note that not all fields are appropriate for some Notice types (eg. lightcurve messages would not have the RA,Dec fields).
0 type_num == A unique number for each pakcet type (as of Aug 2016, this in the 170's). 1 sernum === Serieal number of the packet being sent -- tpyically set to 1. 2 spare === empty slot 3 pkt_sod === the sec-of-day when the packet was sent to GCN (normally used for delivery time delay monitoring). 4 id_num === Some unique identification number for each of the events 5 trigger_tjd === UT, the TJD when the trigger occurred 6 trigger_sod === UT, the seconds-of-day when the trigger occurred 7 ra === The RA location of the the event (usally multiplied by 10,000 and then intergerized) 8 dec === The Dec location of the the event (usally multiplied by 10,000 and then intergerized) 9 intensity === whatever the appropriate units are 10 error === The uncertainty of the location (usally multiplied by 10,000 and then intergerized) 11 other_param_1 === Various parameters associated with the event 12 other_param_2 === Various parameters associated with the event 13 other_param_3 === Various parameters associated with the event 14 other_param_4 === Various parameters associated with the event 15 other_param_5 === Various parameters associated with the event 16 other_param_6 === Various parameters associated with the event 17 other_param_7 === Various parameters associated with the event 18 flags1 === Flagbit fields to capture aspects about the event 19 flags2 === Flagbit fields to capture aspects about the event 20-38 spare === empty slots in the packet 39 eop === end-of-packet marker (set to '\n', remanant of very first packet defined).
2) VOEVENT-SOCKET EXAMPLE:
This methods uses a socket-based VOevent Transport Protocol.
An example of the voevent sent to GCN is here.
3) EMAIL METHOD EXAMPLE: Here is an example using the email method to GCN;
it is a "TOKEN: value" format (that looks very similar to the outgoing full-format email GCN Notices):
Typically, the example message (below) contains other subfields (like units), but those are only needed
for the humans (at your end and my end) to monitor things to see that is all going correctly,
and benefit from the self-documentating aspect.
TITLE: XYZ_EVENT === A unique and connotative identifying type_name DATE: yy/mm/dd hh:mm:ss === When the message was produced (any permutation of yy[yy], mm, & dd accepted) ID_NUM: nnnnnnnn === Some unique identification number for each of the events TRIG_DATE: yy/mm/dd hh:mm:ss === UT, aka EVENT_DATE; when the event was detected (any permutation of yy[yy], mm, & dd accepted, also TJD) RA: dddd.dddd === J2000, but Current (and even B1950) epochs accepted DEC: +-dd.dddd ERROR: d.dd === If containment percentage varies, then we need a field for that number INTENSITY: n.nn === whatever the appropriate units are OTHER_PARAM_1: nn === Various parameters associated with the event OTHER_PARAM_2: nn.nn === They can be interger, floating point, boolean, and short-text fields OTHER_PARAM_3: n.nnE-nn OTHER_PARAM_4: n OTHER_PARAM_5: sssss ... OTHER_PARAM_N: nn FLAGS: 0xFFFF === Flagbit fields to capture aspects about the event COMMENT: Something to say about this event that is typically not numerical. COMMENT: Can be 0-20 lines. === These COMMENT lines get copied vebatum to the full-format email Notices.
4) VOEVENT EMAIL METHOD: The voevent format contains all the same information as listed in the Email Method,
but is in the voevent schema.
An example of the voevent sent to GCN is here.
Here is a table of which ingest method is used for the various missions and projects
that produce notices.
| Method | Who uses that method |
|---|---|
| 1) Binary Socket | Fermi, [HETE] |
| 2) VOEvent Socket | LVC, AMON |
| 3) Email, plain format | CALET, MAXI, IPN, MOA, COUNTERPART, [BeppoSAX, NEAR, ALEXIS, MILAGRO, XTE, Suzaku] |
| 4) Email, VOevent format | nobody as yet |
| 5a) Raw spacecraft telemetry | Swift, [CGRO] |
| 5b) INTEGRAL Custom socket | INTEGRAL |
Testing During Development:
During the development of the new stream of notice types, it is useful to have a way
in which any submitted message to GCN gets distributed ONLY to the you the submitting team.
This fucntionality is supplied two different ways:
a) An entry is put into the "sites.cfg" file which has the enabling flag for the new notice type(s).
Only you will receive the notice, since none of the other entries in the cfg file will be enabled for that type.
This provides an end-to-end closed-loop function.
b) Later on (when the notice type has gone public and other GCN customers have that Notice type enabled,
you can still limit distribution by setting the "internal" flag set in the submission copy.
GCN will distribute that instantiation of the notice only to a specialized entry (your entry) in the sites config file.
Test Notices:
Not all notice types have a separate "test" version -- very few, in fact: 9 out of ~160 types.
Two examples of the 9 are SWIFT_BAT_GRB_POS_TEST and FERMI_GBM_POS_TEST.
It tends to be (a) high impact POSITION types, and/or (c) some special circumstance
that there has sufficient added value to warrent a practice notice type.
A Typical Sequence of Activities to Set-up a New Stream of Notice(s):
a) Initial query about adding a a new type to GCN.
b) Exchange a couple/few emails and telecons to what type(s), how often / come in clusters, what latency(s), what's easiest.
c) I start the new mission-based webpage and the new type(s) to the socket_pkt_def_doc file
(to capture the content, format, and supporting background information).
d) You start sending to GCN -- debug the problems (make adjustments).
e) Decide we are ready to go public.
f) I draft up an announcement email; you make edits (you are the final authority).
g) Announcement is sent out to the current list of GCN customers. (Also add new type(s) to config builder webforms.)
h) Some of the GCN customers ask to have the new notice type(s) added to their configuration.
Closing:
I look forward to incoporating your transients into GCN (GCN/TAN <== All things transient).
Contact Scott Barthelmy if you have questions,
scott@milkyway.gsfc.nasa.gov, 301-286-3106