# Communication specification
## Technical specification
### Hardware
KRAKsat is equipped with [two hardware redundant UHF transceivers](/documentation/sr-nano-bus-platform/untitled.md#cm-module) - parts of SR-NANO-BUS platform.
### Frequency
KRAKsat was assigned coordinated frequency for up- and downlink **435.500 MHz** with emission designator 25K0D1D and EIRP 32 dBm. Downlink modulation is **AFSK 1200bps** and uplink is **2GFSK 9600bps**. Satellite callsign is **SR9KRA.**
## Downlink
KRAKsat downlink communication can be one of three types:
* **beacon** - emitted every 15 minutes
* **commands responses** - specific to uplink type
* **payload logs transmission** - on request, encoded in Base91
{% hint style="info" %}
SR-NANO-BUS downlink can be distinguished by their frames format. Data transceived by UHF1 is decoded as APRS message (with a hardcoded callsign), while data from UHF2 contains frame in APRS telemetry format (without a callsign).
{% endhint %}
### Beacon
Beacon is emitted every 15 minutes by SR-NANO-BUS platform OBC. It consists of 8 frames, sent one by one from both radios. Beacon frames are ASCII strings, terminated by \0, containing information about the status of crucial components.
#### Beacon frame
| | Frame name | Frame value |
| - | ----------------- | ------------------------------------------------------------------------------------------------ |
| 1 | Satellite status | M1;STS;\[User Flags (32-bit value)] |
| 2 | Master status | M1;LOG;\[Timestamp];\[Boot nr];\[CPU voltage];\[CPU temperature] |
| 3 | UHF1 Status | U1;RL;\[Timestamp],\[CPU voltage];\[Battery voltage];\[CPU temperature];\[Amplifier temperature] |
| 4 | UHF1 Modem Status | U1;MS;\[Timestamp];\[Current RSSI];\[Latch RSSI];\[Afc frequency offset] |
| 5 | UHF2 Status | U2;RL;\[Timestamp],\[CPU voltage];\[Battery voltage];\[CPU temperature];\[Amplifier temperature] |
| 6 | UHF2 Modem Status | U2;MS;\[Timestamp];\[Current RSSI];\[Latch RSSI];\[Afc frequency offset] |
| 7 | ADCS Flags Status | A1;FLAGS;\[Fault] \[Flags1] \[Flags2] \[Accelerometer temperature] \[Magnetometer temperature] |
| 8 | Payload status | PL;STATUS;\[Payload status as decimal number] |
Data from frames 1-7 of the beacon status are calculated in SR-NANO-BUS platform OBC. Frame 8 with payload status is prepared in the payload software and updated every minute.
{% hint style="danger" %}
Beacon's first line, master status (M1;STS) is not properly implemented in SR-NANO-BUS platform, so data from 32-bit flags aren't generated correctly.
{% endhint %}
#### Payload status
| Parameter | Bits | Comment |
| ---------------------- | ------- | ---------------------------------------------------------------------- |
| MODE | 0, 1, 2 | |
| NEXT MODE | 3, 4, 5 | |
| µC VOLTAGE | 6, 7 | 0 - correct
1 - too big > 3.7V
2 - too small < 3.0V
|
| SATELLITE VOLTAGE | 8, 9 | 0 - correct
1 - too big > 9.5V
2 - too small < 9.5V
|
| GYROSCOPE | 10 | 0 - correct
1 - error
|
| MAGNETOMETER | 11 | 0 - correct
1 - error
|
| IMU TEMPERATURE | 12 | 0 - correct
1 - error
|
| EXPERIMENT TEMPERATURE | 13 | 0 - correct
1 - error
|
| UNUSED (2 zeros) | 14, 15 | |
{% hint style="danger" %}
**Mode** and **Next mode** values in beacon payload status were encoded as 3-bit numbers while having 9 possible values. This software error caused inability to properly distinguish the current payload state.
{% endhint %}
### Commands responses
Every uplink command has a defined command response, based on which the operator knows if the request was successfully received.
| Command | Action | Response |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ADCS\_LOGS\_ASCII\_GET | Get ADCS FLAGS | A1;FLAGS;\[fault] \[flags1] \[flags2] \[acc temperature] \[mag temperature] |
| AOCS\_ADCS\_CONTROL\_FLAGS\_SET | Set ADCS control flags | |
| BROADCAST\_TIMESTAMP\_SET | Set the current timestamp on the satellite modules | M1; TS; \[number of platform's boot]; \[timestamp set]; \[set value] |
| BROADCAST\_DEV\_RESET | Reboot the satellite | |
| MASTER\_CLEAN\_PLAN | Clear the planner | M1;TSK;CLEAN\_PLAN |
| MASTER\_CMD\_DOWNLINK\_S | Enable/disable downlink for chosen radio | M1;DWN;154;0;1. |
| MASTER\_FLASH\_BLOCK\_ERASE | Erase sector (64kB) of FLASH data from the given address (independent of buffers) | FLASH BLOCK ERASE STATUS;\[address];\[status] |
| MASTER\_FLASH\_SECTOR\_ERASE | Erase the sector (4kB) of FLASH data from the given address (independent of buffers) | FLASH SECTOR ERASE STATUS;\[address];\[status] |
| MASTER\_GET\_NR\_OF\_TASKS | Return the current number of tasks in the planner | M1;TSK;LEN;\[amount of tasks] |
| MASTER\_GET\_PLAN\_G | Return information about the Mission Planner status | M1; TSK; \[task number]; \[time of planned execution]; \[destination module]; \[command] |
| MASTER\_LOG\_G | Get timestamp, boot number, CPU voltage and temperature | M1;LOG;\[TS];\[Boot nr];\[CPU voltage];\[CPU temperature] |
| MASTER\_LOGGER\_INFO | Information about the normal buffer | FL; \[full buffer]; \[amount of used space]; \[start of data address]; \[end of data address] |
| MASTER\_LOGGER\_POP | Remove a given amount of data from the normal buffer, along with the offset of the data origin address | FL; \[full buffer]; \[amount of used space]; \[start of data address]; \[end of data address] |
| MASTER\_PAYLOAD\_STATUS | Return the last received payload status | PL;STATUS;\[payload status] |
| MASTER\_PL\_ADCS\_COIL\_X\_VAL | Set PWM duty for X magnetorquer in manual mode | |
| MASTER\_PL\_ADCS\_COIL\_Y\_VAL | Set PWM duty for Y magnetorquer in manual mode | |
| MASTER\_PL\_ADCS\_COIL\_Z\_VAL | Set PWM duty for Z magnetorquer in manual mode | |
| MASTER\_PL\_ADCS\_COILS\_ALL | Set PWM duty for all magnetorquers in manual mode | |
| MASTER\_PL\_ADCS\_CONFIG\_K\_X | Set the gain for detumbling the X axis | |
| MASTER\_PL\_ADCS\_CONFIG\_K\_Y | Set the gain for detumbling the Y axis | |
| MASTER\_PL\_ADCS\_CONFIG\_K\_Z | Set the gain for detumbling the Z axis | |
| MASTER\_PL\_ADCS\_MAX\_DUTY\_ALL | Set max PWM duty for all magnetorquers | |
| MASTER\_PL\_ADCS\_MAX\_DUTY\_X | Set max PWM duty for X magnetorquer | |
| MASTER\_PL\_ADCS\_MAX\_DUTY\_Y | Set max PWM duty for Y magnetorquer | |
| MASTER\_PL\_ADCS\_MAX\_DUTY\_Z | Set max PWM duty for Z magnetorquer | |
| MASTER\_PL\_CALIBRATION\_CONFIG | Set configuration param
- config param ID
- config param
| |
| MASTER\_PL\_DISABLE | Turn off the payload power supply | |
| MASTER\_PL\_ENABLE | Turn on the payload power supply | |
| MASTER\_PL\_EXP\_ACC\_TIME | Set experiment acceleration time | |
| MASTER\_PL\_EXP\_END\_PERIOD | Set experiment end period | |
| MASTER\_PL\_EXP\_MODE | Set experiment parameters:
-experiment mode
-experiment duty
| |
| MASTER\_PL\_EXP\_PARAMS1 | Set experiment parameters:
- Experiment mode
- Experiment duty
- Experiment period
- Experiment PWM frequency
- Experiment PWM duty
| |
| MASTER\_PL\_EXP\_PARAMS2 | Set experiment parameters:
- Experiment starting period
- Experiment end period
- Experiment acceleration time
| |
| MASTER\_PL\_EXP\_PERIOD | Set experiment period | |
| MASTER\_PL\_EXP\_PWM | Set experiment parameters:
- experiment PWN frequency
-experiment PWM duty
| |
| MASTER\_PL\_EXP\_START\_PERIOD | Set experiment starting period | |
| MASTER\_PL\_FRW\_LIST\_ARG | Set experiment add list element | |
| MASTER\_PL\_FRW\_MAX\_DUTY | Set the max PWM duty for FRW electromagnets | |
| MASTER\_PL\_GO\_IDLE | Set payload to IDLE mode | |
| MASTER\_PL\_LOG1MIN\_CONFIG
\_ADD\_REG
| Provide address of registers that are assigned to the log with a period of 1 min (add) | |
| MASTER\_PL\_LOG1MIN\_CONFIG
\_DELETE\_REG
| Provide address of registers that are no more assigned to the log with a period of 1 min (delete) | |
| MASTER\_PL\_LOG1S\_CONFIG
\_ADD\_REG
| Provide address of registers that are assigned to log with a period of 1000 ms (add) | |
| MASTER\_PL\_LOG1S\_CONFIG
\_DELETE\_REG
| Provide address of registers that are no more assigned to the log with a period of 1000 ms (delete) | |
| MASTER\_PL\_LOG200MS\_CONFIG
\_ADD\_REG
| Provide address of registers that are assigned to the log with a period of 200 ms (add) | |
| MASTER\_PL\_LOG200MS\_CONFIG
\_DELETE\_REG
| Provide address of registers that are no more assigned to the log with a period of 200ms (delete) | |
| MASTER\_PL\_MODE\_CONFIG | Set payload mode with parameters:
-current mode
-next mode
-time for mode
| |
| MASTER\_PL\_WAKE\_UP | Wake up payload from IDLE mode | |
| MASTER\_SPECIAL\_LOGGER\_INFO | Information about the special buffer | FSL; \[full buffer]; \[amount of used space]; \[start of data address]; \[end of data address] |
| MASTER\_SPECIAL\_LOGGER\_POP | Remove a given amount of data from the special buffer, along with the offset of the data origin address | FSL; \[full buffer]; \[amount of used space]; \[start of data address]; \[end of data address] |
| MASTER\_TIMESTAMP\_GET | Get current timestamp from the satellite | M1;TG;\[platforms boot amount]; \[timestamp get] |
| MASTER\_TRANS\_END\_FAIL | End of transaction - failure (no indicator shift) | PL;FINISH;sent = \[address of the indicator];transaction FAIL |
| MASTER\_TRANS\_END\_SUCCESS | End of transaction - success (indicator moved by the amount of data transferred) | PL; FINISH; sent = \[address of the indicator], transaction SUCCESS |
| MASTER\_TRANS\_GET\_CURRENT\_ADDR | Information about the address of the indicator for the current transaction | PL; CURRENT ADDR = \[address of the indicator] |
| MASTER\_TRANS\_SEND\_1KB\_LOG | Launch of a 1kB downlink | PL; \[number 1kB part]; \[chunk number]; \[number of chunks]; \[data]
PL; INFO; WAITING FOR RETRANSMISSION REQUESTS
PL; INFO; NO TRANSACTION IN PROGRESS
|
| MASTER\_TRANS\_SEND\_1KB\_RETRY | Start the retransmission of a given data range within a part (1kB) | PL; R; \[part number]; \[chunk number]; \[data]
PL; RET; \[part number]; \[number of chunks]; 1kB retransmission done
PL; INFO; NO TRANSACTION IN PROGRESS
|
| MASTER\_TRANS\_SEND\_NUM\_PARTS | Initialization of a new transaction | PL;NOP;\[timestamp];\[number of parts in the transaction] |
| MASTER\_TRANS\_SET\_ADDR | Set the address of the indicator for the current transaction | PL; TRANS START ADDR = \[address of the indicator] |
| MASTER\_TRANS\_SET\_CHUNKSIZE | Set the size of a single data chunk in the current transaction | |
| MASTER\_TRANS\_SET\_DATASIZE | Set the amount of data to be sent in the current transaction | |
| MASTER\_TRANS\_SET\_DEFAULT | Set the default transaction parameters | |
| MASTER\_TRANS\_SET\_NORMAL\_DATA
\_START\_ADDR
| Set the normal transaction rate to the beginning address of the data in the normal buffer | |
| MASTER\_TRANS\_SET\_PARTSIZE | Set the size of a single piece of data in the current transaction | |
| MASTER\_TRANS\_SET\_SPECIAL\_DATA
\_START\_ADDR
| Set the special transaction rate to the beginning address of the data in the special buffer | |
| UHF\_CHANNEL\_RX\_G | Get current frequency | U1;CH;\[timestamp];\[current channel] |
| UHF\_CHANNEL\_TX\_G | Get current frequency | U1;CH;\[timestamp];\[current channel] |
| UHF\_FEC\_G | Read FEC flag | U1;FEC;\[fec flag] |
| UHF\_FEC\_S | Set FEC flag (valid only for binary data sent through UHF) | U1;FEC;\[fec flag] |
| UHF\_LOG\_G | Get battery voltage | \[U1;RL;\[timestamp],\[3V3 bus voltage];\[12V bus voltage];\[RF amp temp];\[MCU temp] ] |
| UHF\_MODEM\_STAT\_G | Get radio data | \[U1;MS;\[timestamp];\[current RSSI];\[latched RSSI];\[automatic frequency control offset] ] |
| UHF1\_ECHO | Send an echo | 48byte ASCII STRING |
| UHF2\_ECHO | Send an echo | 48byte ASCII STRING |
{% hint style="danger" %}
SR-NANO-BUS platform contains IMU sensors for ADCS (gyroscope and magnetometer) but because of a software bug, **IMU data can't be transmitted.** It's connected with the fact that instead of being sent as ASCII, frames with IMU data are binary. '\0' sign that is used in APRS as the end of line can be anywhere in ADCS data, so if it's somewhere at the beginning, all the data behind won't be copied to AX.25 frame and transmitted.
{% endhint %}
### Payload logs transmission on request
Payload logs are saved in the flash memory, part of SR-NANO-BUS platform. There is no special way of handling data e.g. filesystem - every new binary frame is just put into the first free memory address, depending on the payload mode (as described in [logging logic](/documentation/software/payload-software.md#logging-logic)).
| Flash memory | Special | Normal |
| ------------ | ----------- | ----------- |
| INFO | 0x0 | 0x1000 |
| CAPACITY | 6MB - 16KB | 2MB - 16KB |
| START | 0x 20 00 | 0x60 00 00 |
| END | 0x 5F E0 00 | 0x 7F C0 00 |
#### Payload log frame
Every log frame contains 6 bytes of information - relative timestamp, register address (key) and register value. Its available parameters and logging interval are specific to the current payload mode. All log frames are prepared in the payload software and transmitted to the OBC as described in [Logging logic](/documentation/software/communication-with-obc.md#logging-logic) chapter.
| Log frame info | Size |
| ------------------ | ---- |
| Relative timestamp | 2B |
| Register address | 2B |
| Register value | 2B |
#### Payload log frames downlink
Log frames downlink is accomplished in form of a **transaction**. First, the transaction has to be initialized and a chosen address set. After that, 1 KB of logs can be downloaded. A part of data consists of chunks (typically 35-38 of them), numbered and encoded in **Base91**. Base91 algorithm used by SR-NANO-BUS platform is so-called [*rlyeh's modification*](https://github.com/r-lyeh-archived/base).
{% hint style="danger" %}
Although UHF1 and UHF2 from SR-NANO-BUS are hardware redundant, their software has some differences. The biggest difference manifests itself in the fact that **logs transmission can be provided only using UHF1**. UHF2 can never transmit log frames.
{% endhint %}
#### Example of payload logs (1 kB)
```
19/07/18:00/12/23:SR9KRA-6:=PL; 0; 0;37;AABtWAAAAAOmUEAAC'WAAAAAOmUE5FAA5A
19/07/18:00/12/24:SR9KRA-6:=PL; 0; 1;37;BAUA^XHnZ4AA,'pB@AoI~+OtCAv|&DDHAA
19/07/18:00/12/25:SR9KRA-6:=PL; 0; 2;37;3+`AKAg@u^McAA`wyB@ArPP&LtCA2OfbDH
19/07/18:00/12/26:SR9KRA-6:=PL; 0; 3;37;uWGXFCoA\20^uWBAyE&MvDAAFAC'CAzDAA
19/07/18:00/12/27:SR9KRA-6:=PL; 0; 4;37;vDuWKAAAKA)_bWMcBtjtrB*B@Q/LRAFAv|
19/07/18:00/12/28:SR9KRA-6:=PL; 0; 5;37;^ADHC'yemAKAR`kpMcC'v~sAoAiay9wWBA
19/07/18:00/12/29:SR9KRA-6:=PL; 0; 6;37;tNiKvDN/YcxAKA?zpVMcBtNuUD*BBtCAC'
19/07/18:00/12/30:SR9KRA-6:=PL; 0; 7;37;CA,BAAvDXLFAC'HAj|1mJVuW#W(A8A5*~t
19/07/18:00/12/31:SR9KRA-6:=PL; 0; 8;37;,\BAk~dBZFBtpJHAPAR`pqSqC'`,QCdBrP
19/07/18:00/12/32:SR9KRA-6:=PL; 0; 9;37;m=LtHA&qEDJVuWGXICdB#TJ:OtHAJJkYJV
19/07/18:00/12/33:SR9KRA-6:=PL; 0;10;37;AAKAAAPALHAAJVBtUAAAoAr?xcuWD'jtrB
19/07/18:00/12/34:SR9KRA-6:=PL; 0;11;37;vD@QcebAKAv|9CMcAAZg#AoAg@^_uWBAr\
19/07/18:00/12/35:SR9KRA-6:=PL; 0;12;37;mA*BrPOVJAFAtx^UGOY4x4GB@Ao.J=BtCA
19/07/18:00/12/36:SR9KRA-6:=PL; 0;13;37;ZCtGDHC'CAAAFA,BAADHXLFAC'MAtZ~nPj
19/07/18:00/12/37:SR9KRA-6:=PL; 0;14;37;uW#W(AJBVx8xyWGA+}\B1RC';7XAZAR`'n
19/07/18:00/12/38:SR9KRA-6:=PL; 0;15;37;e+C'QmRBSCrPwPKtMAgw)RPjuWGXPCSC#T
19/07/18:00/12/39:SR9KRA-6:=PL; 0;16;37;ReBtMAJJZZPjAAKAAAZALHAAPjBtUAAA8A
19/07/18:00/12/40:SR9KRA-6:=PL; 0;17;37;|L$/,\D'jtpBZF@Qg\WAPAv|}BSqAAjyVA
19/07/18:00/12/41:SR9KRA-6:=PL; 0;18;37;8Ag@/]+\BACZKCZF{eFfSAPAV%!fSquWGX
19/07/18:00/12/42:SR9KRA-6:=PL; 0;19;37;OC6C#T-lD'HAyE&MJVAAFAAAPAzDAAJVuW
19/07/18:00/12/43:SR9KRA-6:=PL; 0;20;37;KAAAjA)_FLoICtjtrBOG@Q~(U'RAv|nEVx
19/07/18:00/12/44:SR9KRA-6:=PL; 0;21;37;AAH2.A+Ag@@=@QCAp0WDOG{eFfT'RAs-pT
19/07/18:00/12/45:SR9KRA-6:=PL; 0;22;37;VxuWGXVCHD#TJKKtRAJJ!aVxAAKAAAjALH
19/07/18:00/12/46:SR9KRA-6:=PL; 0;23;37;AAVxBtUAAA@A}4..CtE'jtrBDH@QK0JAUA
19/07/18:00/12/47:SR9KRA-6:=PL; 0;24;37;v||EY4AAtk8A@Ag@1\BtCAGNODDH{eFfRA
19/07/18:00/12/48:SR9KRA-6:=PL; 0;25;37;UA37XsY4uWGXaCvD#T-1EAKAyE3NMcAAFA
19/07/18:00/12/49:SR9KRA-6:=PL; 0;26;37;AAUAzDAAMcuWKAAAtA(n$,0kCtjtrB^H@Q
19/07/18:00/12/50:SR9KRA-6:=PL; 0;27;37;GUD'bAiqInh=uW#W(AmCVx5#2(NA+}bC!m
19/07/18:00/12/51:SR9KRA-6:=PL; 0;28;37;C'd1gA3AR`#o$$D'hD`B-ErP9}JtbA&q8I
19/07/18:00/12/52:SR9KRA-6:=PL; 0;29;37;h=uWGXSC-E#Tq|EtbAJJJZh=AAKAAA3ALH
19/07/18:00/12/53:SR9KRA-6:=PL; 0;30;37;AAh=BtUAAAdB_)FyEtHA,'rByK@QXpCAeA
19/07/18:00/12/54:SR9KRA-6:=PL; 0;31;37;v|&Dk_AAEvgAdB!+z)CtHA=H5KJV[9JRkA
19/07/18:00/12/55:SR9KRA-6:=PL; 0;32;37;8A`ROh+\CtMugEyKjn17CAeAJJUYk_AAKA
19/07/18:00/12/56:SR9KRA-6:=PL; 0;33;37;AA8ALHAAk_BtUAAAnB^X@|aLIA,'rBnL@Q
19/07/18:00/12/57:SR9KRA-6:=PL; 0;34;37;r=L'gAv|yDlBBAX+`AnB!+`!YLIASouD\W
19/07/18:00/12/58:SR9KRA-6:=PL; 0;35;37;[94_iA%A{!^m:CDtMuqEnLjn0WX'gAJJZZ
19/07/18:00/12/59:SR9KRA-6:=PL; 0;36;37;lBBAK
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://kraksat.gitbook.io/documentation/communication/specification.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.