 |
JS8Call de KN4CRD 2026-03-12 - v3.0.0 |
To save an offline copy of the User Guide as PDF download from [here](https://js8call-improved.github.io/downloads/JS8Call_User_Guide.pdf)
JS8Call is an experiment in combining the robustness of FT8 (a weak-signal mode by K1JT) with a messaging and network protocol layer for weak signal communication. The open source software is designed for connecting amateur radio operators who are operating under weak signal conditions and offers real-time keyboard-to-keyboard messaging, stored (inbox) messaging, message relay, and automatic station announcements. JS8Call is heavily inspired by [WSJT-X](https://wsjt.sourceforge.io/wsjtx.html), [Fldigi](http://www.w1hkj.org/), and [FSQCall](http://www.qsl.net/zl1bpu/MFSK/FSQweb.htm) and would not exist without the hard work and dedication of the many developers in the amateur radio community.
**JS8Call stands on the shoulders of giants...the takeoff angle is better up there.**
Read more on the original [design inspiration here.](https://github.com/jsherer/ft8call) For release announcements and discussion, join the JS8Call mailing list here: [https://groups.io/g/js8Call](https://groups.io/g/js8call)
© 2020 Jordan Sherer - This work is openly licensed via [*CC BY-SA*](https://creativecommons.org/share-your-work/cclicenses/).
Because of this special variable encoding, messages in JS8Call cannot be decoded by WSJT-X. The same is also true, WSJT-X messages will not be shown in JS8Call.
### Message Types
Messages come in three forms:
1. standard JS8Call free text messages
2. undirected JS8Call messages
3. directed JS8Call messages
#### Standard Messages
Standard messages are free-text messages that do not start with a callsign or a directed command. These messages will only print at other station locations if they align their receive offset within 10Hz of your transmit offset. This operation is similar to other keyboard-to-keyboard digital modes, like Olivia, RTTY, and PSK.
#### Directed Messages
Directed messages are special JS8Call transmissions that automatically prefix your message with your callsign, similar to how FSQCall operates. Directed messages are useful for communicating in that you do not have to include your callsign in your message, allowing you to use more of the transmission frame(s) for actual message text, as well as alerting the recipient that a message was sent to them. As long as you are in the same passband, you do not have to be on the same frequency offset to receive a directed message.
To send a directed message, all you need to do is include the callsign of the receiving station as the first word in the message or select a callsign in your heard list to have it automatically prefixed.
You'll notice a special character at the end of the message, ala **♢** . This is a symbol to indicate the End of Transmission. JS8Call displays this as after the last frame of the message has been transmitted with nothing else to follow. This means you get a visual indicator that the transmission is done and you can begin transmitting a reply. This character can be customized in the Configuration.
Directed messages to you (and to @ALLCALL) are displayed in the top RX window.
When in the middle of receiving a directed message (i.e., after the first directed frame is received), your station will not respond automatically to commands (even with AUTO on) until that message is received or enough time has elapsed to move on (one minute from the last frame decoded).
#### Group Messages
Group directed messages are specially formatted JS8Call transmissions that announce your station via CQ or Heartbeats (HB) to the @ALLCALL and @HB callsign groups. They are directed at a group destination, but not generally to an individual station.
#### @ALLCALL Callsign
There is a special "@ALLCALL" group callsign that you can use to send the message to anybody who is able to receive your message. Some examples:
- @ALLCALL HELLO NET PSE QSY 14300
- Will be sent as: **KN4CRD: @ALLCALL HELLO NET PSE QSY 14300♢**
#### Group Callsigns
Group callsigns are a custom form of compound callsigns that begin with an "@" character, and can be up to 8 alpha-numeric (A-Z 0-9) characters in length.. If you modeled that in a regular expression, that would be:
``\[@\]\[A-Z0-9\\\]{0,3}\[\\\]?\[A-Z0-9\\\]{0,3}\[\\\]?\[A-Z0-9\\\]{0,3}``
Group callsign functionality allows you to direct your message to anybody who has "joined" the group. You join the group by adding the group name to your settings. All stations who want to receive group messages must add the group to their station configuration. Stations without the group will still be able to see the message received in the band activity, but those messages will not be directed to them.
Say for example, I was part of the Georgia ARES group and I wanted to send other folks in the group a message, I'd send:
`KN4CRD: @ARESGA QSL?`
This group callsign will behave similarly to @ALLCALL. Everybody who has added the @ARESGA group to their station configuration will have the message printed on the screen. If instead, I transmitted:
`KN4CRD: @ARESGA SNR?`
Then, all group member stations who have AUTO enabled would respond with a signal report, similar to if you queried each group station individually.
There are a number of built-in group callsigns that can be transmitted just as efficiently as standard callsigns. All custom groups will require an extra frame during transmission:
| **Continental DX** | **ITU Regions** | **Generic Groups** | **Operator Groups** | **Special Groups** | **Additional Groups** |
|--------|-----------|----------|----------|----------|---------|
| @DX/NA | @REGION/1 | @GROUP/0 | @COMMAND | @JS8NET | @EMCOMM |
| @DX/SA | @REGION/2 | @GROUP/1 | @CONTROL | @APRSIS | @ARES |
| @DX/EU | @REGION/3 | @GROUP/2 | @NTS | @RAGCHEW | @MARS |
| @DX/AS | | @GROUP/3 | @NET | @JS8 | @RACES |
| @DX/AF | | @GROUP/4 | | @AMRRON | @RADAR |
| @DX/OC | | @GROUP/5 | | @CQ | @SKYWARN |
| @DX/AN | | @GROUP/6 | | @HB | @CONTEST |
| | | @GROUP/7 | | @QSO | @FIELDDAY|
| | | @GROUP/8 | | @QSOPARTY| @SOTA |
| | | @GROUP/9 | | @QRP | @POTA |
| | | | | @QRO | @IOTA |
#### @JS8NET and @APRSIS
Available are two "special" groups for spotting. When spotting stations receive messages to these @JS8NET and @APRSIS groups, the messages are posted to the JS8NET spotting server for processing. This allows for specialized functionality to be built to handle these messages. These groups are non-standard, so you cannot add them to your groups list for standard group processing. However, you can send messages to these groups directly (type it into your TX message box, save it to your saved messages, etc).
The **@APRSIS** group is an *experimental* feature allowing APRS messages to be spotted to the APRS-IS gateway. Two message commands are available, GRID for spotting your callsign at a specific location and CMD for sending a raw APRS packet.
For example, any station receiving my message:
`KN4CRD: @APRSIS GRID FN04TV53`
Will submit that spot to JS8NET and spot my callsign at that location to the APRS network. You would then be able to query that spot in an APRS client, like [https://aprs.fi](https://aprs.fi/)
To send a raw frame (say a direct APRS message to SMSGTE), we'd send:
`KN4CRD: @APRSIS CMD :SMSGTE :@5551212 TEST`
Everything after the CMD frame is forwarded in an APRS packet, like:
`[KN4CRD](https://aprs.fi/?c=raw&limit&call=KN4CRD)\>APZJS8,qAS,KN4CRD::SMSGTE:@5551212 TEST`
#### Directed Commands:
There are special directed messages that you can send to stations to have them automatically reply if they have AUTO enabled. They are comprised in the form of \[CALLSIGN\] \[COMMAND\].
- SNR? - What is my SNR?
- GRID? - What is your grid locator?
- INFO? - What is your station information?
- STATUS? - What is your station status message?
- HEARING? - What stations are you HEARING?
-
- \>\[MESSAGE\] - Please relay this message to its destination
- When received in its entirety, the destination station will send an `ACK` reply to the message
- Optionally, this message can be relayed to its final destination through multiple relay stations by prefixing additional callsigns to the message:
- `KN4CRD>HELLO!` (will send the message to KN4CRD)
- `KN4CRD>DR4CNK>HELLO!` (will send the message to DR4CNK through KN4CRD)
- `KN4CRD>DR4CNK>J0Y>HELLO!` (will send the message to J0Y through DR4CNK through KN4CRD)
- Stations will respond to a subset of commands issued through forwarded messages (SNR, INFO, GRID, MSG, MSG TO:, etc) and will reply using the relay path provided.
- Prefixing a directed MSG with the redirect \> symbol when sending to a station in the call list will request the destination station to send an ACK without the MSG going thru the user's Inbox.
- MSG \[MESSAGE\] - Please store and display this message in your inbox
- Your inbox messages can be accessed by right clicking on the callsign and selecting "View Message Inbox..."
- MSG TO:\[CALLSIGN\] \[MESSAGE\] - Please store this message at your station for later retrieval by \[CALLSIGN\]
- Stores a message in persistent storage (on disk) to be retrieved later using the "QUERY MSGS" command.
- \[CALLSIGN\] is the first word after the : and is the final recipient of the message.
- QUERY CALL \[CALLSIGN\]? - Can you communicate directly with CALLSIGN?
- If a station can hear the callsign, they will send back "YES" and then an ACK to that callsign with an SNR report
- QUERY MSG \[ID\] - Please deliver the complete message identified by ID
- QUERY MSGS - Please deliver any messages you have stored for me
- Each response will contain the ID of oldest message yet to be delivered.
- To retrieve the message text, issue a QUERY MSG command with the ID
- AGN? - Have the station automatically retransmit their last message
-
- SNR - Send signal report
- INFO - Send station information
- GRID - Send a long-form grid locator (to be spotted on a map via PSKReporter & JS8NET)
There are also a number of "short messages" that can be included in a directed message frame, which would be transmitted in one tx cycle with standard (non-compound, non-group) callsigns:
- QSL? - Did you receive my last transmission?
- QSL - I received your last transmission
- YES - I confirm your last inquiry
- NO - I negative confirm your last inquiry
- HW CPY? - How do you copy?
- RR - Roger. Received. I copy.
- FB - Fine Business
- TU - Thank You
- 73 - I send my Best Regards
- SK - End of Contact
- DIT DIT - End of Contact / Two Bits
#### Message Examples:
If we wanted to ask DR4CNK what their station information was, we'd send:
- `DR4CNK INFO?`
- And they would respond with a directed message back to us:
`DR4CNK: KN4CRD INFO 50W VERT IN THE SOUTH OF FRANCE`
automatically if `AUTO` reply is enabled.
If we wanted to transmit a "relay" message to OH8STN through DR4CNK, we could use the relay command and send:
- `DR4CNK>OH8STN>HELLO JULIAN!`
- During relay, at each hop the originating sender's call is appended to the message.
- The command above would be received by OH8STN, they would send an ACK back, then retransmit the message, like so:
- KN4 station sends:
`KN4CRD: DR4CNK>OH8STN>HELLO JULIAN!`
- DR4 station relays:
` DR4CNK: OH8STN>HELLO JULIAN! DE KN4CRD`
You can also mix and match standard and free text messages, but most of the time you won't need to.
### Inbox - Message Storage and Retrieval
Directed messaging allows three commands to be used for message storage and retrieval at intermediate stations:
- MSG TO: \[CALLSIGN\] \[MESSAGE\] - Store this MESSAGE at an intermediate station for CALLSIGN
- QUERY MSGS - Query the destination for messages stored for your station callsign
- QUERY MSG \[ID\] - Query for a specific message stored for your station callsign
### AUTO - Automatic Replies
While `AUTO` is enabled, the software will automatically respond to directed queries, like "SNR?", "INFO?", and "GRID?". When `AUTO` is turned off, JS8Call will buffer responses to directed queries in the send message textbox until you are ready to send the replies manually.
If you would like to participate in `AUTO`, but would not like to be responsible for message relays, you can disable relays while `AUTO` is enabled in the settings.
### LOG - Station Log
There's a log item in the main menu of the application. You can also press F5 to start a log entry. The software will do its best effort to pre-populate log fields. However, you'll likely have to fill out some missing information manually since the QSO is free-text and not automated.
The log is stored in JS8Call.log and JS8Call.adif in the log directory (which you can find by clicking "File -\> Open log directory" in the main menu).
Currently, the logging function in JS8Call will log each contact, according to the ADIF spec, as MFSK mode and JS8 submode. There is also an option in the Logging settings to log the mode as DATA instead of MFSK and JS8.
Once logged, the selected directed callsign is automatically deselected by default, however this option can be overridden in the configuration.
### SPOT - Callsign Spotting
When `SPOT` is enabled, JS8Call will report callsigns you hear (or your callsign if heard by other stations) to PSKReporter under the "JS8Call" mode.
JS8Call will also spot GRID commands with 6 or more characters. Make sure to set your grid locator to 6-12 characters for the most accurate spot. You can drill down with this map to your location if you're unsure of your grid: [k7fry grid locator](http://k7fry.com/grid/). If you have a lat/lon, you can also use [QRZ Gridmapper](https://www.qrz.com/gridmapper).
### HB - Heartbeat Transmission
There is an automated heartbeat mechanism that transmits on an interval. You can turn on the HB button by selecting "Enable Heartbeat Networking" from the mode menu. An HB button will then appear on the bottom left. This automated transmission will transmit your grid to the heartbeat network (directed to the @HB group callsign:
`KN4CRD: @HB HEARTBEAT EM73 ♢`
This interval at which the heartbeat transmits can be changed from the control menu or by right clicking the HB button. All heartbeats are transmitted on a random (unused) frequency offset between 500Hz-1000Hz to help prevent QRM. There is an option in the settings to allow heartbeating anywhere...which is especially useful on lower bands like 160m and 630m.
When you have AUTO replies enabled and you've selected to Send Heartbeat Acknowledgements, your station will send an ACK reply to signal to the other operator that you can hear them. These are essentially "lightweight heartbeats" from your station and will reset your heartbeat timer.
The intent of heartbeat is not to report on propagation. Instead it is to help populate your call activity (the heard list on the right) so you know who's likely to be reachable to make contact. You can't work them if you can't "hear" them (or if they cannot hear you).
Keep in mind, though, that HBs are not designed to start conversations. When you turn HB on, you're "joining" the heartbeat network. This network allows for planning of relays and sending messages to be stored at those receiving stations. Think of HBs and ACKs as a way to plot network topology and relays (\"\>\") as a way to send messages to be read later (sort of like an SMS text message) through that network.
While heartbeating, if a station has a message to deliver to another station it hears heartbeating, it will announce that in a HEARTBEAT SNR, like so:
`KN4CRD: KM4ACK HEARTBEAT SNR -12 MSG 32 ♢`
You can then retreive that message using the "QUERY MSG" directed command:
`KM4ACK: KN4CRD QUERY MSG 32`
While in QSO (i.e., when you receive a transmission that is displayed in your incoming messages window) the HB timer will be reset to prevent your station from QRMing your QSO. Versions 2.4.0 and later have "intelligent" HB ACK handling that will disable your automatic HB ACK's if MSG'ing activity is detected in the bandpass. This prevents automated transmissions from QRMing not only your incoming MSG's, but also those of other operators. Both the Mode and Repeat buttons will indicate when the "intelligent" HB ACK handling is in effect by turning off the ACK designator on the buttons (if you have HB ACK's enabled).
Also, keep in mind that unattended transmissions may be against the rules of your jurisdiction. To be most safe, heartbeat should only be automatically sent while you're at the control point of your station. There's an idle timer that you can configure in the settings that will disable your heartbeat once you leave your station idle (no mouse or keyboard movement).
> [!NOTE]
> HBs are intentionally restricted to Slow, Normal, and Fast speeds for bandwidth efficiency and enhanced compatibility in the HB network. HB is disabled and will not appear on the button for JS8 40 and JS8 60
### CQ - Calling CQ
The default way to call cq is with the "CQ CQ CQ" message. This is configured by default. What's notable, though, is that you can configure this message in the settings. These are the messages supported to be sent in one frame transmission:
- CQ CQ CQ
- CQ CQ
- CQ
- CQ CONTEST
- CQ FIELD
- CQ FD
- CQ QRP
- CQ DX
When using one of these message formats, you can also include your 4 digit grid and it will be encoded in one transmission cycle:
- CQ CQ CQ EM73
- CQ CQ BB88
- CQ CC77
- CQ CONTEST FN04
- CQ FIELD AB01
- CQ FD CN01
- CQ QRP JO42
- CQ DX GC28
You can start your CQ message with one of these formats and it will be sent directed, meaning your callsign will automatically be included. You can also add to the messages without issue:
- CQ QRP 500MW CQ?
If you deviate from these formats, you will not be sending a directed message, your grid will not be included, and you must include your callsign in your message.
You can also send CQs on an interval by right clicking the CQ button and selecting a repeat interval. This will cause your station to repeat your CQ transmission until a message is received.
### REPLY - Replying to a CQ
The default way to reply to a cq is with "HW CPY?". This allows the caller to choose who to connect with and send a signal report to. You can customize this message with a reply, but keep in mind that most stations will be replying with something that can be send in one 15-second transmission. Here's an example exchange:
- **→** ``KN4CRD: CQ QRP EM73♢``
- **←** ``DR4CNK: KN4CRD HW CPY?♢``
- **→** ``KN4CRD: DR4CNK SNR -12 TU 4 CALL QSL?♢``
- **←** ``DR4CNK: KN4CRD RR -22 FB INTO GO28 GUD QRP DX!♢``
## Configuration
### Radio (CAT and PTT control)
There is an advanced feature for rig control called PTT Command. This allows JS8Call to execute an external script for controlling a rig's PTT:
What this PTT command does is allow you to execute **any** command line script to toggle your Rig's PTT line.
In the above example, the toggle-ptt script will be called with the `-p 17 and -s parameters` on transmit. The `%1` in the above command will be replaced with "on" or "off" depending on the state of the PTT. If you do not add a `%1` in your command, "on" and "off" will be appended to the end of the command for invocation.
Example:
If you define your PTT command as: ``/usr/bin/ptt %1``
When JS8Call starts transmitting, it will execute: ``/usr/bin/ptt "on"``
And when JS8Call has finished transmitting, it will execute: ``/usr/bin/ptt "off"``
This is particularly helpful for Raspberry Pi / DRAWS when the GPIO ports are used to control your rig PTT. An example script can be found here: [GPIO Toggle Script](https://gist.github.com/jsherer/dd09895ab23bdf571e2117cdd814c198)
### Audio (Sound Card)
When choosing your sound card, you have the option to set individual devices for input and output. You'll need to find the device that matches what you've integrated with your rig. You can choose Mono or Stereo input/output, so try matching those with the capabilities of your device.
For best decoding, when configuring your audio devices you need to apply the right input/output levels:
1. Make sure the sound card device you have chosen for input has no microphone amplification enabled Usually you set this at the operating system level. Set the input to 100%.
2. Move your VFO to a quiet part of the band that has no signals present
3. Set your rig's AF Gain to its maximum value
4. Start adjusting your rig's RF Gain to the point where the s-meter just starts to read 0
5. If RF Gain is not enough to bring down the rig's s-mete, apply your rig's attenuator. This is usual during noisy band conditions or RFI locally. Most attenuators apply a -10dB to -15dB signal attenuation, so you can usually bring RF Gain up just a touch to match.
6. If those adjustments are still not enough, you're likely operating under an extremely noisy condition. You might have luck at this point to start playing with AF Gain to bring the input levels even further down to that sweet spot of 30-60dB as read by the meter in the app.
| Audio input is too low! | Audio input is just right! | Audio input is too high! |
|:-----:|:-----:|:-----:|
|| ||
### Frequencies (Calling Frequencies and Band Hopping)
Most operators testing the application can be found +/- 4-8kHz from the standard FT8 frequencies. It is essential to avoid the main FT8 frequencies, as that will cause confusion among WSJT-X operators. Here are some suggested frequencies to use:
| **Band** | **Frequency** | **Spacing** | **Above/below** | **Mode** |
|--------:|-----------|----------|---------|------|
| 160M | 1.842MHz | 2kHZ | above | FT8 |
| 80M | 3.578MHz | 5kHz | above | FT8 |
| 40M | 7.078MHz | 4kHz | above | FT8 |
| 30M | 10.130MHz | 6kHz | below | FT8 |
| 20M | 14.078MHz | 4kHz | above | FT8 |
| 17M | 18.104MHz | 4kHz | above | FT8 |
| 15M | 21.078MHz | 4kHz | above | FT8 |
| 12M | 24.922MHz | 9kHz | above | FT8 |
| 10M | 28.078MHz | 4kHz | above | FT8 |
| 6M | 50.318MHz | 5kHz | above | FT8 |
| 2M |144.178MHz | 4kHz | above | FT8 |
You might notice a few of these being close to the JT9 frequencies. Don't grab your pitchforks! JS8Call blocks out transmitting within the lower 500Hz of the passband. This leaves enough room for 25 simultaneous JT9 signals.
>[!NOTE]
>You might also notice that there are a few bands missing from this list. JS8Call does not make a recommendation for calling frequencies on 2200m, 630m, 11m (CB), or higher than 2m, as many of these bands are special cases and have unique rules in many jurisdictions. It's up to the operator(s) to coordinate and determine the best frequency and operating pattern on these bands.
But also, please keep in mind these are only *suggested* frequencies. We all have VFOs, so please use them. Just remember to be good operators and prevent from interfering with other signals on our shared bands.
You **CAN** type in any frequency. JS8Call will not limit which frequencies you can manually transmit on. You can use the groups.io mailing list to schedule on other frequencies with test operators.
If you want to transmit on a non-standard frequency (recommended) you can either modify the frequencies list in the settings, or you can type directly into the band dropdown box in the top left of the screen.
