TABLE OF CONTENTS:
This document contains the technical details of the GCN/TAN system: procedures and formats and content definitions of the socket connection method, the e-mail method, the various pager formats/method, and the phone methods. It lists the various Notice types and the filtering capabilities. It is useful to new (potential) sites and for existing GCN/TAN sites as it explains many of the technical issues with the various operation modes, the distribution methods, the various data products distributed, formats, contents, and the quality and accuracy of the coordinates.
Please do not hesitate to contact me with more questions and/or comments.
Scott Barthelmy NASA-GSFC, Code 661, Greenbelt, MD 20771 PHONE: 301-286-3106 (work) (-0677 FAX) EMAIL: scott@lheamail.gsfc.nasa.gov PAGER: 3013463733@cingularme.com (by email, ~2000 characters/message)
There are 3 basic protocols/formats for the socket distribution method:
1) The GCN original 160-byte binary packet,
2) The GCN-custom XML (text, Ver 1.1 & 2.0) VOEvent protocol, and
3) The IVOA VOEvent protocol (XML text, Ver 1.1 & 2.0).
1) The Original GCN 160-byte (binary) packet protocol:
This was the original distribution format created back in 1993.
It consists of a TCP/IP socket connection between the GCN and the customer,
where GCN is technically the "client" end of the connection
and the customer is the "server" end. (This backwards way of doing it
made things easy for GCN back in those early days; and it stuck
for many years.)
The protocol involves sending a single 160-byte binary packet
from GCN to the customer. There are 40 standard 4-byte integer fields
in each packet. All floating point numbers are scaled by multiplying
by 100 or 10,000 and then integerized. This conversion to integers
makes transport across different platforms easier. The recipient
then divides those scaled-fields by the appropriate divisor (100.0 or 10,000.0)
to get the floating point value back native on their platform (eg RA, Dec, Intensity).
As part of the protocol, upon receiving one of these 160-byte packets, the customer immediately
writes back (echos) the packet to complete the loop.
Imalive packets are sent to each connected site every 60 sec
so that both ends can know that the other end is still active
and take the necessary re-initialization steps long before a real GRB/Transient
packet comes along.
2) The GCN-custom XML (text, Ver 1.1 & 2.0) VOEvent protocol:
In 2007 a second TCP/IP-based protocol was set up in GCN.
This uses IVOA VOEvent XML text messages sent from GCN to the customer.
Just like the 160-byte binary protocol/format, this protocol
still has GCN as the "client" end and the customer as the "server"
(for the same motivations as the binary method described above).
This protocol does not require echo-ing back the XML messages.
And there are also imalive XML messages sent every 60 sec;
again so both ends can periodically test the vitality of the connection
before it is really needed for a real GRB/Transient message.
The VOEvent messages are available in both the Version 1.1 format and the Version 2.0 format.
Other information about voevents witin GCN.
3) The IVOA VOEvent (XML text, Ver 1.1 & 2.0) protocol:
In 2012 a 3rd TCP/IP-based protocol was added to GCN.
It also uses the VOEvent XML test messages, but the protocol
is somewhat different in that (a) the customer is now
the technical "client" end of the socket connection
and GCN is the technical "server" end, (b) there are actually
two items sent for each message: a 4-byte binary number
(in network byte order) containing the length of the XML message
and then the XML message itself, and (c) upon receipt
of an XML message the customer needs to respond with an
'ack' or 'nack' status XML message to close the loop
again using the two-compoent 4-byte binry length value
and then the actual XML ack/nack message.
The VOEvent messages are available in both the Version 1.1 format and the Version 2.0 format.
Other information about voevents witin GCN.
Basic Operations (common to methods 1 and 2):
A socket connection typically runs as a 24-hour-a-day operation
(although sites can connect and disconnect at their pleasure).
The software at each end is such, that should the connection
be broken for whatever reason from either end (or the middle),
then automatic reconnection is made by each end.
Status packets are sent out to each socket site every 60 seconds.
These "status" packets are called "imalive" packets in the GCN parlance (type=3).
This exchange of "imalive" packets allows the connection status to be
monitored (I'm OK, you're OK) and a broken connection can be re-made
long before a GRB/Transient packet needs to be sent.
Socket operations at each end (GCN end and site end) are independent of the other. Each end can break a connection for whatever reason and re-make the connection when it suits. Obviously, the GCN end tries to run as much as possible (the GCN livetime is greater than 99%). However, the breaking of a connection by a site does not affect the GCN system or the other sites. When a broken (or missing connection) is discovered (this happens as a write-error at the next imalive packet), GCN goes into a series of (re-)connection attempts. It first tries after 1 minute, then again after 2 minutes, then 4, 8, 16, 32, 64 and then forever at once every 128 minutes. This escalating series of re-attempt times is used, because attempting to connect to one site slightly delays the sending of packets to the other sites that are still connected. The delay is 0.1-3.0 seconds while the attempt to connect is pending.
When GCN has a planned shutdown (2-3 minutes to reload a new copy of the "sites.cfg" file or start new software running), it sends out a Kill packet (type=4) to all the socket sites. This allows the site's software to detect an impending break in the connection and handle it. This extra procedure isn't strictly necessary, but it was easy to code (see the socket_demo.c program discussion below) and it makes it that much more reburst to the vagaries of the Internet.
Differences between the Binary and GCN-XML protocols:
The "original" binary packet method requires that the receiving site echo-back
the packet it just received.
This allows the roundtrip travel time of the connection to be monitored.
As examples,
the connection to the LOTIS (LLNL) system (MD to CA) takes <1 sec,
the ROTSE (LANL) system (MD to NM) takes <1 sec,
MD to Australia takes less than 1 sec, and MD to England takes less than 2 sec
(see a histogram of distribution times).
The new GCN-XML VOEvent packet protocol does NOT require the packets to be echoed back to GCN.
The echoing-back of the binary method was done as an precaution
before much was known about how the Internet behaved on a global scope. Now after 15 years
of experience with the binary, I realize that closed-loop echoing back is not required.
The Internet is very reliable, and the one-ended act of writting to a site's socket connection
at the GCN end is sufficient for GCN to monitor the vitality of the connection.
(If the 'write' fails, GCN initiates a reset and re-connection process.)
Also, the recording of the round-trip time is not important any more -- we now know it is fast.
The differences between the Original 160-byte Binary method and the GCN-Custom XML method
are summarized in Table 1 below.
Differences between protocols 1-and-2 and protocol 3:
The differences between all 3 methods are summarized in Table 1 below.
Because protocol 3 (IVOA XML) runs a true client-server operation (true in the sense
of who is "serving" whom, GCN is serving the customer/client),
there is no need for different port numbers for each customer.
Each client/customer connects to the GCN/TAN server which is listening on port 8099.
Socket Address Specification: Sites wishing to use the socket connection method must specify a "machine.domain" address plus "port number" (e.g. gris1.gsfc.nasa.gov:5111). The "machine" is the name of the computer that will be making the socket connection (e.g. "gris1"), and the "domain" is the domain of the machine (e.g. "gsfc.nasa.gov"). This "port number" is selected by the GCN system administrator from a list of valid values. This "machine.domain:port_num" goes into the "sites.cfg" file.
Daily Socket Connection Status Reports: Socket sites can elect to get daily reports describing the connection status of their connection for the previous 24 hrs. The main things reported are the attempts to connect, disconnect, broken connections, and histograms of the Position-containing packets, the Test packets, and the Imalive packets (type=3) roundtrip travel times. Click for an example of a "daily socket site report".
Socket Disconnection Notices: Sites can also elect to receive automatic e-mails from the GCN system whenever their system is disconnected for more than T1 hours and every T2 hours thereafter. There is a range of T1 & T2 time constants available to choose from. This automated notification is particularly useful since socket sites tend to be automated sites, and the humans in charge may have their attention elsewhere when the connection is broken.
Specific individual(s) can be designated to receive the socket status reports and the disconnection reports. And each of these e-mail lists can be different from the e-mail list I use for administrative communications.
Socket Demo Programs: We have developed 3 programs that are appropriate for the customer-end of a GCN socket (the 'site' end): socket_demo.c, xml_sock_demo.c, and voevent_client_demo.c. They are simple C-language programs with everything you need to setup your end of the connection. There is a place in each program which says "put your instrument-code here" if you choose to use the program as the "main()" starting place for your instrument-control program, or you can extract the various parts relating to the socket operation (open, read, write, and close) to be incorporated into your existing instrument-control program. If you would like to experiment with sockets connections, you can copy socket_demo.c (updated 08oct16) or xml_sock_demo.c (updated 12jun11) or voevent_client_demo.c (update 07mar12). For the binary format method, there is a companion document (Socket Definition Document) that explains the 160-byte binary-packet packing contents & format for all the packet types. For the XML VOEvent method, go to the IVOA site for the version 1.1 document and for the version 2.0 document.
| ITEM | 1 Orig 160B Binary | 2 GCN-Custom XML Protocol | 3 VOEvent Protocol |
|---|---|---|---|
| Who is the Sever | Customer | Customer | GCN/TAN |
| Who is the Client | GCN/TAN | GCN/TAN | Customer |
| Message Style | Binary | ASCII text | ASCII text |
| Message Length | 160 bytes | variable | variable |
| Message Parts | Single packet | Single packet | 4-Byte integer length; N-char ASCII VOEvent |
| Message Format | GCN-custom binary | VOEvent XML | VOEvent XML |
| Protocol | GCN-custom | GCN-custom | IVOA VOEvent |
| Port Number | GCN-assigned | GCN-assigned | 8099 |
| Customer Response | Echo the packet | Echo the packet | Send Ack/Nack |
| Imalives sent | Yes | Yes | Yes |
| KILLs sent | Yes | Yes | No |
| Reconnection Times | 4,8,16,32,64,64,64,... min | 4,8,16,32,64,64,64,... min | Whenever the customer wants |
| Disconnection Notification | Yes | Yes | Vetted Sites: Yes Anonymous: no |
| Transport Layer | TCP/IP | TCP/IP | TCP/IP |
| Pre-Registration | Yes | Yes | Yes and No[1] |
| Message Filtering | Yes | Yes | Yes and No[1] |
| Demo Program | socket_demo.c | xml_sock_demo.c | voevent_client_demo.c |
| Publishing | Only by special connection | No[2] | Yes[3] |
Footnotes:
[1] Pre-registered (in the sites.cfg file) is allowed for the VOEvent (method 3) connection
and this enabled Message Filtering. But anonymous connecting is also allowed.
[2] I prefer that you use the Original GCN 160-byte protocol (or email) (and both by special arrangement
than the GCN-Custom XML protocol. (GCN will turn the 160-byte into XML and redistribute it.
[3] Technically, publishing (in VOEvent protocol) is not yet allowed. (It is implemented,
but the authentication method is not complete. Soon, vetted connected will be allowed to publish,
and later, anonymous connections will be allowed to publish.)
The e-mail method of distributing the GCN GRB locations is probably the easiest to explain -- it uses the normal Internet electronic mail that we have all come to know and love (and hate :-)), and use many times in the course of our daily research activities. It is not the fastest form of distributing the coordinates, but it is no slouch either. Timing trials showed that between MD & Kitt Peak, AZ and also between MD & CA (LLNL) the delivery time ranged from 5 to 20 seconds.
Even the e-mail method is amenable for "automated" systems/instruments, because it is a simple matter to write a process (a daemon) which monitors incoming mail (to a specific person/id and/or a specific subject-line) and parse the body of the e-mail to get the coordinates, etc. Once extracted, it is a simple matter to get these data values into other programs (e.g. the instrument-control program). Procmail (.procmailrc file rules) allows for the detection, filtering, and taking action based on the From-line, Subject-line, and even the contants of specific incoming emails.
It is quite common for sites that have human operators located at the instrument to have a special login account set up to which the GCN e-mail notices are sent. Sometimes this is an "operator" account which is the generic account already in existence for the operation of the telescope, and sometimes this is a new generic account (e.g. "burst_alert"). In either case some way of getting the attention of the human operator is used when an incoming notice arrives. For UNIX systems, this often takes the form of using the "biff y" command (usually in the ".login" file). Biff will beep the terminal and display the first few lines of the e-mail. This combined audio and visual alerting mechanism gets the operator's attention. Or just have a window open with a mail-reader program running.
There are two distribution/transport sub-methods:
a) EMAIL -- the original way, and
b) LMAIL -- the "list mail" way. Same contents and format as EMAIL, just a faster delivery method.
The LMAIL method is the preferred method for those customers wanting the full-format email notice.
If the customer has a specific reason for not wanting the preferred LMAIL way
(he needs the To-line to have his address instead of the generic listmail filename),
then he will be given the EMAIL method.
Click for examples of the l-/e-mail notices for the various sources of GRB coordinates. Click for the full details of the full-format email format and content definition document.
This sends XML-formated messages via email to the address specified.
say more stuff.
Click for examples of the XML e-mail notices for the various sources of GRB coordinates. See the individual mission/instrument-based web pags for descriptions of the contents of VOEvent XML messages.
Pagers: The distribution of GCN locations by pagers ("beepers") is available. Alpha-numeric pagers have the ability to display up to 240 characters (and up to 400-600 characters for the new units). (In the late 1990's this was true, but now with "smart phones", there is no character-count limitation. Smart-phones have greatly reduced the need for these various versions/sizes of pager-based notice formats.) An example of the text for an "Original" message is shown below:
GCN/SWIFT_BAT
GRB Position
RA=303.93d DEC=+41.79d
ERR=3.0arcmin
T=13:12:32.20 UT
I=613
R_signif=32.34
I_signif=7.13
Definite GRB
It starts with a Title "GCN/SWIFT_BAT GRB".
The RA & Dec of the burst location plus the Time and the initial Intensity
are given. The RA,Dec are in Current Epoch.
One or two short comment fields are also given:
a phrase designating the trigger type (GRB, Solar Flare, etc), and
if the location is of a nown source in some catalog.
The other notice types have essentially the same basic format and
slightly different contents (for the details and examples).
Short Pagers:You can also choose to receive a "short" form pager message. An example of the body of the short-pager message is shown below:
SWIFT
BAT GRB Position
RA=303.52 DEC=+41.64
Everything but the RA,Dec fields have been eliminated.
This is useful for those people/sites with pager units with smaller capacity.
For the Short Pager message, the RA,Dec are in 1950 Epoch (for reasons
that are historical, but other arrangements can be made for new sites).
The other source types have essentially the same basic format and
slightly different contents (for the details and examples).
Only the RA,Dec values (decimal degrees format) appear in the subject-line of the e-mail sent to the pager or cell-phone. This handles the situation for those people who have access only to a pager (or cell-phone) service company that will only display the From-line and the Subject-line of the e-mail sent to the customer. These companies will not display the "body" of the e-mail, so the pertinent information must be placed in the only field that is accessable (controllable) by the sender (GCN). Click for the details and examples of the Subject-only notices.
The RA,Dec (in hh:mm:ss dd:mm:ss format), UT time, and Intensity values appear in the subject-line of the e-mail sent to the pager or cell-phone. This is a slightly longer format than the Subject-only (see above) format in that (1) it contains the time of the burst and (2) the intensity. It also has the RA,Dec location in hh:mm:ss,dd:mm:ss format instead of decimal degrees. This handles the situation for those people who have access only to a pager (or cell-phone) service company that will only display the From-line and the Subject-line of the e-mail sent to the customer. These companies will not display the "body" of the e-mail, so the pertinent information must be placed in the only field that is accessable (controllable) by the sender (GCN). Click for the details and examples of the Subject-only HH:MM notices.
All 3 of the commonly used epochs are used in expressing the coordinates in the various distribution methods. This variety stems from (a) flexibility (as in the case of the email method displaying all 3 epochs), and (b) from user-preferance (as in the case of the site that motivated the creation of the short-pager method needed 1950 epoch, etc.).
| 1950 | current | J2000 | |
|---|---|---|---|
| Socket (Binary) | was | X | |
| Socket (XML) | X | ||
| Socket (VOEvent) | X | ||
| Email/Lmail | X | X | X |
| XML | X | ||
| Pager | X | ||
| SPager | X | ||
| Subject | X | ||
| Subject hh:mm | X |
The mixture of the various epochs used for the "Pager", "Short Pager", "Subject-only", and "Subject-only hh:mm:ss" methods is a result of the epoch preference by the first site to first request such a distribution format/method (i.e. they were created for their convenience and are now available to all other sites).
Originally, the Socket packets used the "current" epoch values, but now all the packets of the missions that are active all have J2000 epoch.
GCN has (and has had) many notice types (~105 as of May 2011) over the years. The set of active notice types is dynamic: missions come and go, ground-based producers come and go, types within missions/instruments come and go. The full list of notice types can be found in a table here. The third column in that table indicates which are active, which are no longer available (defunct), and whcih are being developed (in-work). The table also lists which formats each notice type is available and which filtering functions are applicable. There are some obvious omissions (e.g. Imalives are not available via the e-mail and pager methods -- it would be most annoying to receive a pager notice once every minute). Also, there is too much data (number of bytes) in the BATSE LightCurves (Text, PostScript, and JPEG) to fit within the Socket, (S)Pager, and Subject-only distribution methods.
And here are brief descriptions of active notice types (with links to their fuller descriptions). (The discontinued notice types can be found here.)
IPN_POS: The "IPN_POS" position notices (type=39) containes the burst location information from a full 3-s/c IPN triangulation solution. One or two error boxes are reported. More details are given in the IPN_Pos Notice data product.
INTEGRAL: The "INTEGRAL" notices (types=51-56: POINTDIR,SPIACS,WAKEUP,REFINED,OFFLINE, and WEAK) are GRB locations as determined by the INTEGAL-IBIS/-SPI instruments. They are discussed in more detail in the INTEGRAL data product.
Swift: The "Swift" notices (types=60-99: positions, lightcurves, spectra, images, etc) are GRB locations/images/etc as determined by the Swift-BAT/-XRT/-UVOT instruments. They are discussed in more detail in the Swift data product.
AGILE: The "AGILE" notices (types=100-102,107-109) contains the GRB positions and spacecraft pointing_direction.
Fermi: The "Fermi" notices (types=110-115,118-129) contains the GRB positions and spacecraft pointing_direction.
MAXI: The "MAXI" notices (types=134-136) contains the Unknown- and Known-source positions and Test notices.
LVC: The "LIGO-Virgo" notices (types=150-154) contains skymaps of location probability for gravitational wave events (binary mergers).
AMON: The "AMON" notices (types=157, 158, 169) contains the IceCube neutrino events and coincidences between different instruments.
SIMBAD-NED Searches: The SIMBAD and NED databases are queried for objects near the coordinates of GRB and Transients. Only the small error-circle Mission-Instrument Notices (<20armin) have companion SIMBAD-NED searches; the large error-circle Notices do not initiate a search.
Pointing Directions: The INTEGRAL, Swift, AGILE, and Fermi missions all provide the pointing direction information of the respective spacecraft. This can be used for ground-based telescopes to "follow along" taking data even prior to receiving the a GRB Notice.
Lightcurves: The Swift-BAT, KONUS-Wind and NEAR-XGRS produce lightcurves of triggered events.
Counterpart: The "Counterpart" notices (type=45) contains the position of counterparts detected by follow-up observers. They are discussed in more detail in the COUNTERPART data product.
MOA: The "MOA" notices (type=139) contains the position of gravitational microlensing event detected by the MOA telescope. They are discussed in more detail in the MOA data product.
DOW_TOD: The "DOW_TOD" (Day-of-Week Time-of-Day notices (type=48) is a special notice type that allows the receiver to monitor their connectivity (usually cell/pager email-based) by getting a notice at a user-specified time-of-day on user-specified day(s)-of-the-week. They are discussed in more detail in the DOW_TOD notice type.
And for socket-based sites, there are two more notice types (Imalive and Kill).
These are not dis/enable controllable; socket sites always get these two types.
They are part of the protocol for the socket distribution method.
Imalive: Socket sites and dedicated phone sites get "imalive" packets (type=3). These are sent every 60 seconds by the GCN system. The recipient sites is expected to echo-back the packet. This closed-cycle process allows GCN to monitor for broken connections. Timing the round-trip travel time also allows for monitoring the quality of the link (actually this is only appropriate for socket sites). For more details on the Imalive Notices.
Kill: Socket sites also get "kill" packets (type=4) when the GCN system is being shut down in a controlled manner (as opposed to a crash). These kill packets alert the site's software to make a controlled closing of the socket connection from their end as well. Unlike all other packet types, kill packets are not supposed to be echo-written back to GCN (because GCN is in the process of shutting down). The site's software should drop into a mode of periodically checking to re-open the socket connection. For more details on the Kill Notices.
Misc: The other types (5-10, 12-21, & 23) are used for internal communications between the various programs which make up the GCN system. GCN customers will never get these types.
The full list of notice types can be found in a table here. The fourth group of columns in the table (labeled "Type-Specific Filters) indicates which filtering functions are available at which type.
Introduction:
There are 16 dimensions of filtering:
Notice Type (default is disabled),
Error Size (default is 360 deg),
Time Delay (default is infinity),
Intensity (it is units specific; default is 0 or 99 for mag-based notice types),
Significance (signal to noise ratio; default is 0),
Confidence (default is 0),
Trigger_ID (default is 0),
Sun_distance (deg; default is 0),
Sun_hour_angle_dist (hours; default is 0),
Moon_distance (deg; default is 0),
Moon_Illumination (%; default is 100),
Celestial coords (RA,Dec ranges; default is 0-360,-90-+90),
Galactic coords (Lon,Lat ranges; default is 0-360,-90-+90),
Ecliptic coords (Lon,Lat ranges; default is 0-360,-90-+90),
Time-of-day window (default is 0-24),
Observability (All, Visible, Night, [custom]).
The meaning of each filtering parameters are:
Notice_type: The notice type has to be enabled to be received.
Error_size: The location error has to be less than the specified value.
Time_delay: The time delay has to be less than the specified value.
Intensity: The intensity has to be greater than the specified value.
Significance: The significance [sigma] has to be greater than the specified value.
Confidence: The confidence level [%] has to be greater than the specified value.
Trigger_ID: The trigger identity has to be what the TypeName says (ie no false positives).
Observability: The observability has to be All, Visible, Night, .
Sun_distance: The distance (in deg) to the Sun has to be greater than the specified value.
Sun_hour_angle_dist: The delta_RA hour_angle (lead or lag) has to be greater than the specified value.
Moon_distance: The distance (in deg) to the Moon has to be greater than the specified value.
Moon_illumination: The Moon illumination has to be less than the specified value.
Celestial_coords: The location has to be within the specified RA,Dec ranges.
Galactic_coords: The location has to be within the specified Gal_Lon,Lat ranges.
Ecliptic_coords: The location has to be within the specified Ecl_Lon,Lat ranges.
Time-of-day_window: The notice time has to be within the specified time window (UT).
The table below lists all the filter functions (new and old ways),
and it lists which functions are Global (i.e. applies to all notice types)
and which are Type-specific (i.e. can be specified for each of the notice types).
Type-specific override any Global specifications. (The original 6 filter functions were Global
in the old way.)
FILTER PARAM | NEW WAY(1) | OLD WAY(1)
| Global | Type-Specific(4) |
=================================================================================
Notice_type | X(3) | X | X
Error_size | X[!] | X | X
Time_delay | X[!] | X | X
Intensity | X[!] | X | X(2)
Significance | X[!] | X |
Confidence | X[!] | X |
Trigger_ID | X(3) | X | X
Observability | X(3) | X | X
| | |
Sun_distance (deg) | X[!] | |
Sun_hour_angle_dist (hr) | X[!] | |
Moon_distance (deg) | X[!] | |
Moon_illumination (%) | X[!] | |
| | |
Celestial coords (RA,Dec ranges) | X[!] | |
Galactic coords (Lon,Lat ranges) | X[!] | |
Ecliptic coords (Lon,Lat ranges) | X[!] | |
Time-of-day Window | X[!] | |
Table Notes:
(1) An "X" indicates that the given function is implemented in the Old or New ways.
Note that the first 8 filter rules are applicable at the global level
(i.e. to all Notice Types) and at the Type-by-Type level.
The next 8 filter rules (new way) are only applicable at the global level.
If you want different, say, Gal Lon,Lat values for different Notice Types,
then you will have to create two entries with the desired Types in each entry
with the different Gal Lon,Lat ranges.
(2) Intensity filtering was applicable to only the BATSE-based notice types (Old way).
Now it is applicable to all notice types that contain an intensity field;
and since it can be specified on a Type-by-Type basis, the different units and
dynamic ranges of intensities of each Type can be handled appropriately.
(3) There is no negation operation for the global Source_Type, Trigger_ID, and Observability.
If you don't want, say, SWIFT_BAT_POS, then don't enable it.
There is almost no practical need for the negation of Trigger_ID.
And it makes no practical sense to implement a "not visible" observability filter.
Negation capability on a filter function is indicated by the "[!]".
(4) There is no negation operation for the Type-specific filters.
There are 16 criteria used to determine which sites get sent which notices.
Each site has complete freedom of choosing which selection criteria
they want to use.
All 16 of these filtering criteria act independently of each other. A site's "configuration" contains specifications for each of the 6 parameters for determining which Notices they will receive. As an example, a site can choose to receive only Swift-BAT_POS and Fermi-LAT_UPDATE notices that are VIS to their instrument's location AND have location uncertainties less than 0.5 degrees AND are being distributed in less than 4.0 hours after the initial burst time.
1) Notice Type Selection: There are dis/enable flags for each site for each Notice type. For the current set of active missions, instruments, and other contributors, there are 14 Swift-based notice types, 7 Fermi-based, 6 INTEGRAL-based, 4 AGILE-based, 1 IPN type, and 1 Counterpart type.
2) Local Observability: There are 3 filter functions which use the GRB's location on the site's local sky position to determine if the notice is sent or not. The ALL filter function means that the site get the notice independent of the GRB's local azimuth,elevation location. The VIS function means that the GRB's local elevation angle must be greater than 10 degrees above the site's local horizon. The NIGHT filter uses the VIS filter plus the additional requirement that it be civil twilight at the site (i.e. the Sun must be more than 6 degrees below the local horizon).
3) Intensity Threshold: The Intensity threshold filter is applied to all notice types that have an intensity field. (For those types that do not have an intensity field, the Intensity filter is skipped.) Since all the notice types with intensity fields have different units and dynamic ranges, the global-level Intensity field should never be used; it should be specified on the type-specific form. (Please note that because of the shape of typical GRB lightcurves and that most instrument trigger as soon as possible, the initial Notice will have an intensity value near their threshold.)
For notice types that contain a 'magnitude', the threshold testing is reversed. For example, the UVOT_POS has magnitude values in the intensity field. If the "intensity threshold" specifies inten=20, then only UVOT_Postion notices with the 'intensity' field value less than 20.0 will be sent to the customer.
4) Error Size: The Error_size filter allows sites to receive only those Notices for which the uncertainty in the location is less than X.X amount (X.X is in units of degrees; 0.0-360.0 with 0.36arcsec quantization).
5) Time Delay: The Time_delay filter quantity allows sites to receive only those Notices that are being distributed within X.X hours after the GRB. This filter has become necessary since the addition of burst-source contributors that are not real-time operations (IPN, Counterpart, and human-in-the-loop update Notices from other real-time missions).
6) Significance: This is similar to Intensity filtering, only it works in the signal-to-noise range (instead of the instrument-specific units). Here the units are sigma.
7) Confidence Level: Currently, there are only 2 notice types that have a Confidence Level in their data packet: SWIFT_BAT_TRANS and GRB_COUNTERPART. The filtering code is such, that for all the other notice types that do not have an associated ConfLevel, they are never blocked by the filtering code (i.e. those notice types have a defacto ConfLevel of 100%; the filter function is always satisfied no matter what ConfLevel you choose).
8) Trigger_ID:
Currently, there are only 3 notice types that have a Trigger_ID
in their data packet: SWIFT_BAT_GRB_POS, SWIFT_FOM_2OBS, and SWIFT_SC_2SLEW.
The Trigger_ID filter allows sites to get notices
for only those Swift-BAT triggers that were caused by real GRBs.
This is particularly useful for sites with "consumables"
(eg. human effort required to make the observations, photographic emulsions, etc).
Since this filter function is ~90% accurate in keeping the real GRB triggers
(it misses only ~10% of the real GRBs), then little is lost when eliminating
those non-GRB triggers which are only ~10% as abundant as the real GRBs.
Even sites that choose not to enable the Trigger_ID filtering,
can still perform the filtering at their end because the trigger identification
type is in included in all notification methods (id_type flags in the socket
and phone packets, and there is an identification in the COMMENTS field
in the e-mail and pager notifications).
And for those notice types that do not have trigger_identity capaility,
this filter function has not affect (they all pass).
9) Sun_distance: (deg) For those notice types containing a position of a GRB/Transient source, then that location has to be farther from the Sun (in true sky angle) than the specified value. The units are degrees, and the default is 0 deg.
10) Sun_hour_angle_dist: (hr) For those notice types containing a position of a GRB/Transient source, then that location has to have an RA_hour angle from the Sun's RA_hour angle greater than the specified value. The units are hours, and the default is 0 deg.
11) Moon_distance: (deg) For those notice types containing a position of a GRB/Transient source, then that location has to be farther from the Moon (in true sky angle) than the specified value. The units are degrees, and the default is 0 deg.
12) Moon_illumination: (%) The current Moon illumination percentage has to be less than the specified value. This is a way to specify "dark time" vs "bright time".
13) Celestial coords: (RA,Dec ranges) For those notice types containing a position of a GRB/Transient source, then that location has to be within the specific RA range and the specified Dec range.
14) Galactic coords: (Lon,Lat ranges) For those notice types containing a position of a GRB/Transient source, then that location has to be within the specific Galactic Longitude range and the specified Latitude range.
15) Ecliptic coords: (Lon,Lat ranges) For those notice types containing a position of a GRB/Transient source, then that location has to be within the specific Ecpliptic Longitude range and the specified Latitude range.
16) Time-of-day Window: The Notice time (time of generation; not the time of the event) has to be within the specific time-of-day window (e.g. if you specify 3.0 and 10.0 (UT), then GCN will send you only the notices types you have enabled that were received by GCN between those hours.
Examples:
And all of these can be reversed (negated). The "!" character
(as a suffix to the Token) is used to "reverse" the meaning of the filter range.
Example: The normal way to exclude notices during bright Moon time:
MOON_ILLUM 50
This will block all notices when the Moon is brighter than 50% illumination.
But if you want notices when the Moon IS bright
(eg. you have bright-time on a telescope to make near-IR observations):
MOON_ILLUM! 50
This will pass notices when the Moon is brighter than 50% illumination
(and block everything when the Moon is fainter than 50% illumination).
Other Examples:
If you wanted events ONLY on the Galactic Plane, then
GAL_LAT_LIM -20.0 +20.0
or if you want everything off the Plane (i.e. nothing IN the Plane)
GAL_LAT_LIM! -20.0 +20.0
If you only want items in the Galactic Bulge:
GAL_LON_LIM 340.0 +20.0
GAL_LAT_LIM -20.0 +20.0
If you have a northern hemisphere telescope, you can restrict
the Declination to what you can observe:
CEL_DEC_LIM -30 +90
If you only want items in the LMC:
CEL_RA_LIM 75.4 86.5
CEL_DEC_LIM -74 -64
The GCN system gets everything it needs to know about a site
from information in the "sites.cfg" file.
It a simple ASCII text file which contains 3 groups of information for each site:
1) Site administrative information,
2) Site-level filtering information,
3) Type-level filtering information.
Here is an example of an entry in the "sites.cfg" file:
BEGIN_SITE # Site_administrative items: SITE_NAME SBLmailAll DATES 03jun93 28may09 SITE_LON_LAT -77.45 38.85 DIST_METHOD LMAIL DIST_ADDRESS scott@milkyway.gsfc.nasa.gov ATTACHMENT FITS POC_NAME Scott Barthelmy POC_ADDRESS scott@milkyway.gsfc.nasa.gov DAILY_REPORT_ENABLE 1 DAILY_REPORT_ADDRESS scott@milkyway.gsfc.nasa.gov # Site-level filtering items: INTENSITY -1 TRIGGER_ID 0 ERROR 360.100 DELAY 999.900 SIGNIFICANCE 0.00 CONF_LEVEL 0.00 OBSERVABILITY ALL SIMBAD_NED 1 # Type-level filtering items: ... SWIFT_BAT_GRB_POS [inten=X] [error=Y] [delay=Z] [signif=S] [conf=P] [obs=all/vis/night/custom/etc] [trig_id=1/0] [sim_ned=1/0] [attach=sss] ... FERMI_LAT_POS_UPD [inten=X] [error=Y] [delay=Z] [signif=S] [conf=P] [obs=all/vis/night/custom/etc] [trig_id=1/0] [sim_ned=1/0] [attach=sss] FERMI_SC_SLEW FERMI_POINTDIR END_SITE
In the example above I have deleted most of the notice types (as indicated by the "...") and left just 4 types. Two of the 4 have explicitly shown the 9 optional type-specific filtering parameters (as inficated by the square brackets (eg. "[inten=X]")).
And here is an example for the old format (used until March 2011):
SBLmailAll -77.45 38.85 -1 360.1 999.9 8FFB FF7E 3fff ffff fffc fcfc 1 1 1 1 1 9 0 f7f Cf 0 ALL FITS LMAIL scott@lheamail.gsfc.nasa.gov D C ; 03jun93 28may09
Publication references that describe the original BACODINE system and then the expanded GCN system.
Barthelmy, S.D., et al.; in "Proceedings of the Second Huntsville GRB Workshop"; ed. G.Fishman, J.Brainerd, K.Hurley; 307; 643; 1994. Barthelmy, S.D., et al.; ESLAB29 Symposium -- Towards the Source of GRBs; Noordwijk; Klewar; Ap&SS; 231; 235; 1995. Barthelmy, S.D., et al.; in "Proceedings of the Huntsville Third GRB Workshop"; AIP, New York; in press; 1996. Barthelmy, S.D., et al.; in "Proceedings of the 4th Huntsville GRB Workshop"; ed. G.Fishman, J.Brainerd, K.Hurley; 428; 99; 1998. Barthelmy, S.D., et al.; in "Proceedings of the 5th Huntsville GRB Workshop"; ed. R.M.Kippen, R.Mallozzi, G.Fishman; 526; 731; 2000.