TABLE OF CONTENTS:
This document contains the technical details of the GCN 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 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) (-1684 FAX) EMAIL: scott@lheamail.gsfc.nasa.gov PAGER: 3013463733@cingularme.com (by email, ~200 characters/message)
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.Kippem, R.Mallozzi, G.Fishman; 526; 731; 2000.
There are two basic protocals/formats for the socket distribution method:
1) The original 160-byte binary packet, and
2) The XML (text) VOEvent packet.
Basic Operations (common to both methods):
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 & 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 strickly 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 XML methods:
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 XML VOEvent packet method does 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 -- it is fast.
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 two programs that are appropriate for the receiving-end of a GCN socket (the 'site' end): socket_demo.c and xml_sock_demo.c. They are a 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 or xml_sock_demo.c using the 'save as plain_text' option of your browser. For the binary format method, there is a companion document (Socket Definition Document) that explains some of the constructs in the source code, the socket-packet packing contents & format for all the packet types. For the XML VOEvent method, go to the IVOA site for the document.
Socket Test Program (Binary method only): I also have a program (socket_test) which simulates the GCN program (the Goddard end of the connection). This is useful for developing the program at your end, because the socket_test program can be killed and restarted without effecting the operations of the other sites, and the rate of the imalive and (simulated) coords packets can be controlled (both the rate of occurence and the coordinate locations). Having a higher than normal rates for these two packet types makes the edit/compile/debug loop shorter at your end.
This socket_test program can be run in parallel to the real GCN socket connection (only the port numbers have to be different). This is useful for developing a new version of code at your end without interrupting existing GCN/your_instrument operations.
This socket_test.c software is not for distribution. I run it here at GSFC on the GCN machine. Whenever a new site wants to use this GCN simulation program, they make a request (just like for normal ops) and I will set up a test account. (Unlike the socket_demo program, this socket_test program can not be distributed; it is huge and complex and it is easier for me to run the socket_test at the user's request, than to support the zillion questions that would result if it were out in the user-community (it's rough to port it to new machines).)
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 (say, 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. Click for the full details of the e-mail format and content definition document.
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). An example of the text for an "Original" message is shown below:
BACODINE GRB
RA=303.93d DEC=+41.79d
TIME: 13:12:32.20 UT
I=613
Definite GRB
COMPTEL FOV.
It starts with a Title "BACODINE 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 within the COMPTEL instrument's FOV then there appears
a phrase for that.
(The later is useful as a heads-up for a potential forthcoming smaller
error box.)
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:
ORIGINAL
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).
Coverage: The problem with the beepers is getting coverage in your area. They tend to cover only large metropolitan areas (within ~20miles of cities greater than ~50K people). In addition to the United States, there are also about a dozen countries in the world with coverage. This was the situation circa Late 1995. I suspect that progress in technology and market forces have increased the coverage situation (1) for smaller cities, (2) for longer distances from each transmitter, and (3) for more countries. The delay time is 1-3 minutes depending on time-of-day and geography. In addition to the macro-coverage factor of the distance from the transmitter, there is also the micro-coverage due to being inside a metal building. I have found the 930MHz band very effective in getting through all-metal buildings, inside automobiles, and inside commercial airplanes at 35000 feet.
Testing: Beeper sites can also specify that they want test notices sent every N days at a specified time-of-day (this way you don't get test beeped in the middle of the night). This is a way of monitoring "if the pager company still thinks you are a valid account". It's also a way of building confidence about the coverage and reception quality of your unit at your specific location. This testing is much faster than realizing you are missing those "burst" notices that come at a much lower occurance (on average).
Utility: Beepers are nice (1) for people who are away from their telescopes and e-mail accounts but still want to know if something important has happened so they can "log in", and (2) for sites with no Internet connection (i.e. no e-mail and no sockets capability).
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 pertinant 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 pertinant 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.
Dedicated: There is also a capability to connect via a dedicated phone line connection with modems. The connection is made at the beginning of night (for optical and radio systems that require ionospheric radio quiet times) and hangs up just before sunrise. This is the fastest method: 0.3 sec delivery time. But it is also the most expensive. Back in 1994 it was about 20K$ for phone line charges for 365 sessions of 12 hours each at long-distance rates for cross-country. "Imalive" connection monitoring packets are exchanged every minute (just like the Internet socket connection method) and "burst" packets are sent whenever there is a burst. The content of these packets is very similar to the socket method, and detailed format specifications for these packets are available on request.
Dialed:The dialed phone connection method uses the same protocols as the "dedicated" method except that the phone/modem/computer connection is made at the time of the burst instead of ahead of time. This saves a lot of money because of the greatly reduced connect time, but the penalty is an increase in the time delay between the beginning of the burst and the receipt of the coordinates.
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 | ||
| 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.
The message types that are available are the "BATSE-Original", "Test coordinates", "Imalive", "Kill", "BATSE-Maxbc", "BATSE-Final", "BATSE-Locburst", "COMPTEL", "ALEXIS", "RXTE-PCA", "RXTE-ASM", "SAX-WFC", "SAX-NFI", "IPN_POS", and INTEGRAL, HETE, and Swift message/packet types. These messages are available through most of the distribution methods. The table below lists which Distribution Methods are available for the various Notice Types. 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.
| Socket | Pager | S-Pager | Subject | SubjHH:MM | XML | Phone | WebPage | ||
|---|---|---|---|---|---|---|---|---|---|
| BATSE-Original | x | x | x | x | x | x | x | X | |
| BATSE-Final | x | x | x | x | x | x | x | X | |
| BATSE-MAxBC | x | x | x | x | x | x | x | X | |
| BATSE-Locburst | x | x | x | x | x | x | x | X | |
| BATSE Text LC | x | X | |||||||
| BATSE PS LC | x | X | |||||||
| BATSE GIF LC | X | ||||||||
| COMPTEL | x | x | x | x | x | x | x | X | |
| RXTE-PCA | X | X | X | X | X | X | x | x | X |
| RXTE-ASM | X | X | X | X | X | X | x | x | X |
| SAX-WFC | x | x | x | x | x | x | x | x | x |
| SAX-NFI | x | x | x | x | x | x | x | x | x |
| IPN_RAW | X | ||||||||
| IPN_SEG | X | X | |||||||
| IPN_POS | X | X | |||||||
| ALEXIS | x | x | x | x | x | x | X | ||
| MILAGRO | x | x | x | x | x | x | x | x | X |
| Counterpart | X | X | X | X | X | X | X | X | |
| HETE (all) | x | x | x | x | x | x | X | X | |
| INTEGRAL (all) | X | X | X | X | X | X | X | X | |
| Swift (all) | X | X | X | X | X | X | X | X | |
| AGILE (all) | X | X | X | X | X | X | X | X | |
| Fermi (all) | X | X | X | X | X | X | X | X | |
| PIOTS_OT | X | X | X | X | X | X | X | X | |
| SIMBAD_NED | X | ||||||||
| Orig_Test (t=2) | X | X | X | X | X | X | X | x | |
| HETE_Test (t=44) | X | X | X | X | X | X | X | ||
| INTEGRAL_Test (all) | X | X | X | X | X | X | X | ||
| Swift-BAT_Test (t=82) | X | X | X | X | X | X | X | ||
| AGILE_Test (t=109) | X | X | X | X | X | X | X | ||
| Fermi-GBM_Test (t=119) | X | X | X | X | X | X | X | ||
| Fermi-LAT_Test (t=124) | X | X | X | X | X | X | X | ||
| INTEGRAL_PointDir | X | X | X | X | X | X | X | ||
| Swift_PointDir | X | X | X | X | X | X | X | ||
| AGILE_PointDir | X | X | X | X | X | X | X | ||
| Fermi_PointDir | X | X | X | X | X | X | X | ||
| Imalive (t=3) | X | ||||||||
| Kill (t=4) | X |
BATSE-Original: The "original" GRB coordinates notices (type=1) are for a location derived from the BATSE LAD count rates from an actual BATSE flight processor trigger. While the BATSE trigger may not be due to a real GRB (e.g. see discussion about ID types: solar flares, electron precipitation events, etc), it is the response of the GCN system to a BATSE trigger. Click for more information on BATSE-Original Notice data product. This is no longer available since the de-orbit of CGRO.
BATSE Test Coordinates: "Test coords" messages (type=2) are just that -- they are messages initiated by the GCN program (not the BATSE instrument) and contain RA,Dec coordinate locations chosen from a predefined list by the GCN program. They are generated at a user-specified rate and allow the site to test the response of their system to notices at a controlled and higher rate than the real "grb coordinates" notifications. For more details on the Test Notices.
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.
BATSE-MAXBC: The "MAXBC" notices (type=11) are locations based on the 16 maximum (peak) count rates determined by the on-board flight software in a 10 minute interval after the initial trigger. For more details on the BATSE-MAXBC Notice. This is no longer available since the de-orbit of CGRO.
BATSE-Final: The "Final" notices (type=22) are based an integration of up to the first 32sec of the BATSE light curve to yield a location. They are discussed in more detail in the BATSE-Final Notice data product. This is no longer available since the de-orbit of CGRO.
BATSE-LOCBURST: The Locburst Coordinates notices (type=24) are an improved version of the Original/Final/MAXBC Notice GRB locations (above). They have a smaller location error (0-2 deg statistical plus a 2 deg systematic). This is a factor of 2-5x better than the Original GRB Coords, but they have a 15-25 min delay. Click for more information on the BATSE-LOCBURST Notice data product. This is no longer available since the de-orbit of CGRO.
COMPTEL: The "COMPTEL" notices (type=30) are GRB locations as determined by the CGRO-COMPTEL instrument. They are discussed in more detail in the COMPTEL data product. This is no longer available since the de-orbit of CGRO.
ALEXIS: The "ALEXIS" notices (type=25) are for extreme-UV (60-90eV) transients. They are discussed in more detail in the ALEXIS data product. This is no longer available.
RXTE-PCA: The "RXTE-PCA" notices (type=26 & 27). The RXTE-PCA team has started a program to make ToO observations of bright GRBs detected by BATSE. They are discussed in more detail in the RXTE-PCA data product.
RXTE-ASM: The "RXTE-ASM" notices (type=28 & 29). The RXTE-ASM instrument detects several GRBs per year in its FOV. The locations for these are automatically processed and made available to the follow-up community through the GCN. They are discussed in more detail in the RXTE-ASM data product.
SAX-WFC/-NFI: The "SAX-WFC/-NFI" notices (type=34 and 36) are GRB locations as determined by the BeppoSAX-WFC/-NFI instruments. They are discussed in more detail in the SAX data product. This is no longer available.
IPN_RAW: The "IPN_RAW" annulus notices (type=31) containes (a) 1-s/c timestamp-only ntoices of GRB detections, and (b) the raw 2-s/c IPN triangulation annulus solutions. This is no longer available.
IPN_SEG: The "IPN_SEG" annulus segment notices (type=32) containes the burst location information of the intersection of the IPN annulus (from the Ulysses-BATSE solution) and the BATSE Orginal/Final/MAXBC/LOCBURST location error circle. More details are given in the IPN_Pos Notice data product. This is no longer available since the de-orbit of CGRO.
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.
MILAGRO: The "MILAGRO" notices (types=58) contains the position of air showers initiated by high-energy gamma-rays and cosmic rays. (High energy means above ~100 GeV.) This is no longer available.
HETE: The "HETE" notices (types=40-43: Alert,Update,Final,GndAna) are GRB locations as determined by the HETE-WXM/-SXC instruments. They are discussed in more detail in the HETE data product. This is no longer available.
HETE_Test Coordinates: "HETE_Test coords" messages (type=44) are just that -- they are messages initiated by the GCN program (not the HETE s/c) and contain RA,Dec coordinate locations chosen from a predefined list by the GCN program. They are generated at a user-specified rate and allow the site to test the response of their system to notices at a controlled and higher rate than the real "grb coordinates" notifications. For more details on the Test Notices.
INTEGRAL: The "INTEGRAL" notices (types=51-55: POINTDIR,SPIACS,WAKEUP,FREFINED, and OFFLINE) 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-129) contains the GRB positions and spacecraft pointing_direction.
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 KONUS-Wind and NEAR-XGRS produce lightcurves of triggered events ........... This is not yet available.
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.
PIOTS: The "PIOTS_OT_POS" notices (type=131) contains the position of optical transients detected by the Pi-of-the-Sky telescope. This is not yet available.
Misc: The other types (5-10, 12-21, & 23) are used for internal communications between the various programs which make up the GCN system.
Introduction: There are 6 major criteria used to determine which sites get sent which notices. Each site has complete freedom of choosing which selection criteria they want to use. The 6 major criteria are (1) the source selection, (2) the visibility (standard or custom) filtering, (3) intensity thresholding, (4) location uncertainty (error box size), (5) time delay (between GRB time and Notice distribution time), and (6) trigger ID type filtering.
All 6 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 BATSE-Final and SAX-WFC 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 AND (if BATSE) have an intensity greater than 1000 counts/sec AND have a Trigger_ID determined to be defintely GRB.
1) Source Selection: There are dis/enable flags for each site for each source of GRB location information (i.e. BATSE, RXTE-PCA, RXTE-ASM, COMPTEL, IPN, & ALEXIS). Some of the sources have notice subtypes. BATSE has Original, Final, MAXBC, LOCBURST, and Light Curve notice subtypes. The RXTE-PCA has Alert "will" & "won't" and Position "saw" & "no_saw" subtypes. The RXTE-ASM has Alert and Position subtypes. Sites have separate dis/enable flags for each subtype which the GCN program uses to determine if they should get that pareticular subtype notice.
| TYPE | SUB-TYPE | Master | Sub-Type |
|---|---|---|---|
| Dis/enable | Dis/enable | ||
| BATSE (nla) | x | ||
| Original | x | ||
| Final | x | ||
| MAXBC | x | ||
| LOCBURST | x | ||
| Text LC | x | ||
| Postscript LC | x | ||
| COMPTEL (nla) | x | ||
| Observation (saw) | x | ||
| Observation (null) | x | ||
| RXTE-PCA | X | ||
| Alert (will obs) | X | ||
| Alert (won't) | X | ||
| Observation (saw) | X | ||
| Observation (null) | X | ||
| RXTE-ASM | X | ||
| Observation | X | ||
| ALEXIS (nla) | x | ||
| SAX-WFC (nla) | x | ||
| Observation (saw) | x | ||
| Observation (null) | x | ||
| SAX-NFI (nla) | x | ||
| Observation (saw) | x | ||
| Observation (null) | x | ||
| HETE (nla) | x | ||
| Alert | x | ||
| Update | x | ||
| Final | x | ||
| GndAna | x | ||
| IPN_RAW (nla) | n/a | ||
| IPN_SEG (nla) | X | ||
| IPN_POS | X | ||
| MILAGRO (nla) | x | ||
| Counterpart | X | ||
| INTEGRAL WAKEUP | X | ||
| INTEGRAL REFINED | X | ||
| INTEGRAL OFLINE | X | ||
| INTEGRAL SPIACS | X | ||
| INTEGRAL POINTDIR | X | ||
| Swift BAT Alert | X | ||
| Swift BAT Position | X | ||
| Swift BAT Position Nack | X | ||
| Swift BAT Lightcurve | X | ||
| Swift FOM 2Observe | X | ||
| Swift SC 2Slew | X | ||
| Swift XRT Position | X | ||
| Swift XRT Position Nack | X | ||
| Swift XRT Lightcurve | X | ||
| Swift XRT Image | X | ||
| Swift XRT Spectra | X | ||
| Swift UVOT DarkBurst | X | ||
| Swift UVOT FindChart | X | ||
| Swift BAT Processed Lightcurve | X | ||
| Swift XRT Processed Image | X | ||
| Swift XRT Processed Spectra | X | ||
| Swift UVOT Processed DarkBurst | X | ||
| Swift UVOT Processed FindChart | X | ||
| Swift POINTDIR | X | ||
| SuperAGILE Wakeup Position | X | ||
| SuperAGILE Ground Position | X | ||
| SuperAGILE Refined Position | X | ||
| AGILE POINTDIR | X | ||
| Fermi-GBM Flight Position | X | ||
| Fermi-GBM Ground Position | X | ||
| Fermi-GBM Lightcurve (not yet) | X | ||
| Fermi-GBM Internal (not public) | X | ||
| Fermi-GBM Transient (not yet) | X | ||
| Fermi-LAT Initial Pos (not public) | X | ||
| Fermi-LAT Updated Position | X | ||
| Fermi-LAT Diagnostic Pos (not public) | X | ||
| Fermi-LAT Ground-Refined Position | X | ||
| Fermi-LAT Ground-Triggered Position | X | ||
| Fermi POINTDIR | X | ||
| PIOTS_OT (not yet avail) | X | ||
| SIMBAD_NED | X | ||
| BATSE Original Test | X | ||
| HETE Test | X | ||
| INTEGRAL Test | X | ||
| Swift-BAT Test | X | ||
| AGILE Test | X | ||
| Fermi-GBM Test | X | ||
| Fermi-LAT Test | X |
2a) Local Visibility: 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).
2b) Custom Filters: There are also several "special" filter functions. For the COMPTEL, EGRET, and OSSE instrument teams, GCN notifies them when there is a GRB in their FOV, respectively. Thus in the "sites.cfg" file these sites use the COMPTEL, EGRET, or OSSE filter functions, respectively. GCN can also determine if a GRB is in the FOV of other spacecraft. A special filter function was set up to determine if a location was inside the ASCA sun_angle band. Another special filter function (the anti-solar hemisphere) has been set up for the ALEXIS spacecraft. These heads-up notifications for these instrument teams are nice examples of how GCN has managed to meet the needs of a diverse community. GCN has also created a special filter functions for the ground-based HEGRA and WESTERBORK instruments (i.e. is the GRB location in their respective observable Declination bands). And there is also an RXTE ToO selection criteria filter function (it is the intensity greater than X, the location uncertainty is less than Y, and the GRB location must be greater than 35 degrees from the sun).
3) Intensity Threshold: The INTENSITY threshold filter is applied after any ALL, VIS or NIGHT filter selection. It is applied to only the BATSE-Original/-Final/-MAXBC/-LOCBURST notice types. The other spacecraft sources of GRB locations do not have an intensity threshold filtering capability (it was felt that they did not need such a filter, and it is hard to impliment because of the mixed units.) Before there was the TRIGGER_ID filter function, some sites elected to have a greater than zero threshold level to limit the number of non-GRB notices they received. This worked because at each given intensity level, the fraction that were real GRBs increased with intensity -- the non-GRB triggers tended to be clustered near the BATSE threshold. At 1500 the triggers are ~90% real GRBs, and at 2000 it's ~95%. Some sites still use the INTENSITY threshold filter to receive only the brighter GRBs. This is useful because the brighter the GRB, the smaller the BATSE-Original/-Final/-MAXBC/-LOCBURST error circle. Thus for sites with FOVs on the small side, it made sense only to receive notices that matched their FOV.
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). This continuously adjustable error_box_size filters replaces the two fixed-value filters (ERROR_1d and ERROR_2m, 1degree and 2arcmin respectively).
5) Time Delay: The Time_delay filter quantity allows sites to receive only those Notices that are being istributed 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) Trigger ID: Swift Era: 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"
(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).
CGRO-BATSE era: The TRIGGER_ID filter allows sites to get notices
for only those BATSE triggers that were caused by real GRBs.
This is particularly useful for sites with "consumables"
(human effort required to make the observations, photographic emulsions, etc).
Since this filter function is 98% accurate in keeping the real GRB triggers
(it misses only 2% of the real GRBs), then little is lost when eliminating
those non-GRB triggers which are almost twice 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).
Trigger_ID filter currently applies ONLY to the Swift-based notices (and BATSE-based notices
in the past). The other
sources of GRB locations (e.g. RXTE, COMPTEL, etc) are always due to real
GRBs -- there is never any "contamination" of notices due to non-GRBs.
TABLE 9: The Various Filter Criteria
Source Type/Subtype Which sources of burst information (see Table 8)
ALL Site gets everything (i.e. no Visible or Night filter)
VIS GRB's Elevation angle > 10deg (at the site)
NIGHTTIME Sun's Elevation angle < -6deg (plus VIS)
Trigger_ID No non-GRB Swift-BAT triggers are sent to the site
Intensity Intensity > X (BATSE-only; X is site-specific)
Errorsize The "diameter" of the location uncertainty is < X.X deg
Time_delay The time between GRB and Notice distribution is < X.X hours
Custom Filters: COMPTEL FOV, EGRET FOV, OSSE FOV,
ASCA sun_angle band (i.e. 65-115 deg),
ALEXIS FOV (i.e. the anti-solar hemisphere),
HEGRA FOV (i.e. is it in HEGRA's Declination band),
NYTT FOV (i.e. is it in their Declination band),
WESTERBORK FOV (i.e. is it in their Declination band),
Meets RXTE-PCA ToO criteria,
and others.
TABLE 10: Which Filters are Available for Each Source Type
Type ALL VIS NITE Custom TrigID Inten ErrBox TimDelay Test
BATSE-Original X X X X X X X X
BATSE-Final X X X X X X X X
BATSE-MAXBC X X X X X X X
BATSE-Locburst X X X X X X
BATSE Text LC X X X X X X
BATSE PS_LC
COMPTEL X X X X X X
ALEXIS X X X X X X
RXTE-PCA X X X X X X
RXTE-ASM X X X X X X
SAX-WFC X X X X X X
SAX-NFI X X X X X X
IPN_RAW
IPN_SEG
IPN_POS X X X X X X
MILAGRO X X X X X X
COUNTERPART X X X X X X
HETE_Alert X X X X X X
HETE_Update X X X X X X
HETE_Last X X X X X X
HETE_GndAna X X X X X X
INTEGRAL_PDIR
INTEGRAL_SPIACS
INTEGRAL_WAKEUP X X X X X X
INTEGRAL_REFINED X X X X X X
INTEGRAL_OFFLINE X X X X X X
Swift-BAT_Alert X X X X X
Swift-BAT_Pos X X X X X X X
Swift-BAT_PosNack X X X X X X
Swift-BAT_LC X X X X X X
Swift-FOM_2Obs X X X X X X
Swift-SC_Slew X X X X X X
Swift-all_others X X X X X
AGILE-all X X X X X
Fermi-all X X X X X
PIOTS_OT X X X X X
SIMBAD_NED X X X X X
BATSE_Orig_Test X
HETE_Test X
INTEGRAL_Test X
Swift-BAT_Test X
AGILE_Test X
Fermi-GBM_Test X
Fermi-LAT_Test X
Notes:
1) There is not enough information to make a reliable Trig_ID for the MAXBC's.
2) Trigger_ID filtering is is only applicable to BATSE-based and Swift-based Notices.
3) Test notices do not have Trig_ID filtering because it doesn't make sense
and they have their own control flag.
4) The Curstom filters are: HEGRA_FOV, Westerbork_FOV, ASCA_sun_angle,
COMPTE_FOV, EGRET_FOV, OSSE_FOV, ALEXIS_FOV, and several time-of-day_windows,
and several declination_bands.
5) The Intensity threshold filter applies only to the BATSE-related notices.
The units are counts_per_1or2_sec in the 50-300keV LAD band.
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:
1) The name of the site (up to 12 characters, mostly for human identification use), 2) The longitude & latitude of the site (needed for local visibility & day_vs_night calculations), 3) The GRB error_circle_size threshold level filtering requirement, 4) The GRB Notice-time-delay threshold level filtering requirement, 5) Dis/Enables for the various locations sources (HETE, BeppoSAX, RXTE, ALEXIS, etc), 6) Dis/Enable flags for receiving: Test Notices & Socket Non-connection Notices, 7) The ALL/VIS/NIGHT/"special" filter function selection, 8) The distribution method (socket, e-mail, phone, pager), and 9) The destination address (socket address with port number, e-mail address, etc).
It is a very simple matter to edit this file to change a site's configuration, or to add a new site, or remove a site.