Commit c2d97c0b authored by Frank Lars Zimdars's avatar Frank Lars Zimdars Committed by Bernd-Christian Renner
Browse files

Small corrections

parent 6290e4f1
......@@ -93,7 +93,7 @@ The Mainboard has six LEDs indicate the status of the modem.
</table>
!!! info "Info"
The indicator levels are rough estimates based on a 3S LiPo battery with 12.4 V nominal rating.
[A](/tutorial_firmware/#fw_batlevels)
If you want to change it see tutorial [Customising the Firmware](/tutorial_firmware/#fw_batlevels)
## Connectors
......@@ -245,8 +245,7 @@ It comprises two pin header connectors, one for power supply (C1) and one for ex
!!! warning "Info"
The hydrophone **must** be connected to the TX board. If your hydrophone has a separate shield and two connection wires, connect them as indicated on the table. If your hydrophone only has a single wire and shield, connect the shield to H- and do not connect the shielding on the TX board.
## Accessories
......@@ -268,6 +267,11 @@ Alternatively, you can also use a 12V power supply, like a bench power supply. I
![Figure 9](/images/accessories/banana.png "12V Banana")
!!! warning "Unfused"
The modem has no integrated fuse. Be careful when the batterie is connected. Short cuts will damage the board.
Add a fuse or use the current limit at the power supply, to avoid bigger damages.
### Serial Communication
To communicate with the modem, a USB-to-serial adapter is required. The external I/O connector (C2) is designed to accept a TTL-232R-3V3 adapter with 6-pin female connector directly.
......
......@@ -24,9 +24,15 @@ Toolchain:
* [https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads)
* [https://cmake.org/download/](https://cmake.org/download/)
Misc:
* [https://docs.microsoft.com/en-gb/windows/wsl/install-win10](https://docs.microsoft.com/en-gb/windows/wsl/install-win10)
https://sourceforge.net/p/stm32flash/wiki/Home
*[https://www.st.com/en/development-tools/stsw-link004.html](https://www.st.com/en/development-tools/stsw-link004.html)
# Firmware
# Compile and flash the Firmware
## Installation
### Installating the toolchain
The Install the GNU Tools for ARM Embedded Processor (see Resources for the link). Follow the installation instructions.
The first step is to install the toolchain (compiler). Here the GNU Tools for ARM Embedded Processor (see [Resources]( /resources) for the link) are used.
Follow the installation instructions.
Make sure that the installation is registered in the environment variable.
!!! note "Version"
The firmware is designed with Version 7-2018-q2-update. Newer version could be used, but it is possible that there might changes in the behaviour.
The firmware is developed with Version "7-2018-q2-update". Newer version could be used, but it is possible that there might be small changes in the behaviour.
### Installing Make
The next step is to install make.
......@@ -20,9 +19,7 @@ Under linux just type:
```
sudo apt install make build-essential
```
Under windows "make" is not available as standanlone application, but you can use the version installed by MinGW.
Under windows "make" is not available as standanlone application, but you can use the version installed by MinGW. Just make sure to select it during the installation.
### Installing CMake
......@@ -30,29 +27,32 @@ Under windows "make" is not available as standanlone application, but you can us
CMake is only nessesary for using the (alternative) CMAKE script or the st-flash-tool. If you don't use one of them you can skip this section.
CMake is a tool to generate build script for different compiling systems and plattforms.
Different compiler are possible through CMake, the source code itself uses syntax available only in the gcc.
CMake is a tool to generate build scripts for different compiling systems and plattforms.
Even different compilers are possible through CMake, but the firmware source code itself uses syntax available only in the gcc.
For linux type:
```
sudo apt install cmake build-essential
```
For windows you can download and install the compiled application direct from the website (link can be found in [Resources](/resources)).
### Install WSL (for makefile build under windows)
The make file is written for Linux (bash). Without changes it is not possible to use it under Windows.
To be able to use it despite the limitation under windows, the “Windows Subsystem Linux” [(See Resources: WSL)](/resources) can be used.
To be able to use it under windows, despite this limitation , the “Windows Subsystem Linux” can be used.
Follow the link WSL on the [Resources page](/resources) to prepare/enable it.
Afterwards you can use the windows store and search for “Linux”. Different distributions should appear. Choose one you like and install it.
The bash can be started with the command “bash” in the command line. Alternative the name of the distribution also starts the bash shell.
The bash can now be started with the command “bash” in the command line. Alternative the name of the distribution also starts the bash shell.
At the first start, it takes some time to prepare the installation. Remember the username and password you choose.
The windows filesystem is mounted at “/mnt/”. For “C:\” the path inside the bas is “/mnt/c/”.
The windows filesystem is mounted at “/mnt/”. For “C:\” the path inside the bash is “/mnt/c/”.
Beware of different line encoding between Windows and Linux. Also, the brackets of the path change between “/” and “\”.
It is possible to call windows application from the bash. To avoid complications, prefer the Linux version of the tools and install them inside the bash.
It is possible to call windows application from the bash. To avoid complications, prefer the Linux version of the tools and install them directly inside the bash / WSL-Environment.
Before any packets can be installed, the list of the package manager has to be updated, with the following commands:
```
......@@ -60,11 +60,11 @@ sudo apt-get update && sudo apt-get upgrade
```
!!! info "Info"
Using WSL you have now a linux system and should follow the linux instructions in the following sections.
Using WSL you have now a linux system and can/should follow the linux instructions in the following sections.
### Installing flash tools
Dependencies:
Install the Dependencies:
```
sudo apt install make cmake libusb-1.0.0-dev build-essential
```
......@@ -80,17 +80,18 @@ In Ubuntu Linux, you may simply install the STlink version provided instead:
sudo apt install stlink-tools
```
Under Windows you can use also the [ST-Link Utility](/resources) (with GUI).
## Compiling the firmware
Clone the Git [AHOI firmware](/resources) repository using:
Clone the AHOI firmware repository using:
```
git clone URL
```
### commandline, using make
Replace URL with the current address of the repository, found in the [resources page](/resources).
### commandline (using make)
#### configuration
......@@ -106,7 +107,7 @@ repository.
#### Building
!!! warning "Bug: No automatic recompilation"
If the configuration becomes changed, no automatic recompilation is started!
If the configuration is changed, (sometimes) no automatic recompilation is started!
Go to the source directory and type the following command:
......@@ -121,11 +122,11 @@ hardware platforms:
tx boards:
- single
- bridge (default)
- **single**
- **bridge** (default)
### commandline, using cmake
### commandline (using cmake)
!!! warning "Under development"
......@@ -135,29 +136,26 @@ tx boards:
!!! info "Missing features"
The following features are at the moment not (correct) implemented:
- no automatic version name from git
- no automatic version name from git and manual defined in the cmake script
- target "sim" not working
#### configuration
The file "CMake_env_stm32_gcc.cmake" contains a toolchain configuration, prepared for the gcc-arm-eabi (GCC ARM Crosscompiler). It uses the environment variables.
If you have multiple installations or you don't want to rely on the environment variables, you can write the file path of the tools direct in this file.
If you have multiple installations or you don't want to rely on the environment variables, you can write the file paths of the tools directly in this file.
The file "CMakeLists.txt" contains the description, how the firmware should be build. The hardware configuration has to be done directly in this file.
The file "CMakeLists.txt" contains the description how the firmware should be build. The configuration/selection of build flags has to be done directly in this file.
At the moment three targets are avaiable:
At the moment three targets are included in the script:
| Target | Description |
| ----- | ------- |
| ahoi_firmware.elf | Default firmware |
| ahoi_firmware_legacy.elf | Firmware for legacy hardware, only nessesary if you have an old modem. Doesn't support all features |
| ahoi_firmware_legacy.elf | Firmware for legacy hardware, only nessesary if you have an old modem. May not support all features |
| ahoi_firmware_sim | PC Programm, to simulate the programm |
The description inside the CMake script consists of four parts (source files, include files, definitions, linker setting)
Each target has its own entrys.
......@@ -174,19 +172,19 @@ For the definitions "target_compile_definitions(...)" is used.
#### building
Specify a build system generator, using the command:
To prepare cmake, using the build system generator, type the command:
```
cmake cmake -S . -B OUTPUT_FOLDER -G "Makefiles" -DCMAKE_TOOLCHAIN_FILE="CMake_env_stm32_gcc.cmake"
```
cmake -S . -B OUTPUT_FOLDER -G "Makefiles" -DCMAKE_TOOLCHAIN_FILE="CMake_env_stm32_gcc.cmake"
```
The parameter "S" specifies the source directory. If it is the same folder, as the one you execude this command use " . ".
"B" specifies the build output directory (here named build). If the folder doesn't exist it fill be created automaticly.
Please use an different folder as the build directory, so all generated files can be found in one folder and no files of the source folder are overwritten (escpallially the makefile).
"B" specifies the build output directory (here named OUTPUT_FOLDER). If the folder doesn't exist it fill be created automaticly.
Please use an different folder as the source directory for output, so all generated files can be found in one folder and no files of the source folder are overwritten (especially the makefile).
Replace "Makefiles" with the Make system you use. Following this manual the valus should be:
Replace "Makefiles" with the Make system you use. Following this manual and the previous chapters the values should be:
- Linux: "Unix Makefiles"
- Windows: "MinGW Makefiles"
......@@ -211,8 +209,7 @@ CMake should show a list, which programs is has found and will use.
```
!!! tip "Tip"
Check that the listed programs are the correct ones.
Check that the listed programs are the correct ones which you expect. Sometimes more than one gcc (arm-eabi-none) toolchain can be installed on a pc and the automatic detection may not work.
Afterwards cmake is ready to start the compiling. Use the following command:
......@@ -232,25 +229,35 @@ If the compillation was succesfull you should see at the end of the log an simil
If you don't see an size but the 100% line, the binary was already build and cmake decided that no new compillation was nessesary (unchanged source files).
To start a new compiler run, no noew call of the system generator is necessary. Just type the build command.
## Flashing the firmware (using programmer)
Attach the programming adapter to modem (mainboard).Connect a STlink-v2 programmer to programming adapter and PC.
Power the modem by external 12V (it is not powered through programmer).
If you use the makefile (and the st-link tools) a special option is avaiable:
```
make t=stm [tx=<tx board>] program
```
This command will start the compillation and will afterwars automaticly start the programming using st-flash (not the ST-Link Utility!).
If you have already a (release) firmware binary (e.g. with the name "firmware-file.bin"), starting the programming directly with the following command is possible:
## Flashing the firmware
```
st-flash write <firmware-file.bin> 0x8000000
```
- connect programming adapter to modem
- connect STlink-v2 programmer to programming adapter and PC
- power modem by external 12V (it is not powered through programmer)
- make t=stm [tx=<tx board>] program
OR
st-flash write <firmware-file.bin> 0x8000000, if you want to flash a release image
- if only the blue POWER LED is lid after flashing, restart the modem or remove programmer/programming adapter
(the top LED should be blinking as an indicator that the modem works properly)
If only the blue POWER LED is lid after flashing, restart the modem or remove programmer/programming adapter
(the top LED should be blinking as an indicator that the modem works properly).
## Check and prepare the modem
After the firmware is successfully flashed on the modem it is ready to become initialized.
- connect serial cable (FTDI 3V3) to modem and PC
- connect a serial cable (FTDI 3V3) to modem and PC
- run MoSh and check that it responds to, e.g., a "version" command
- you have to set the ID of the modem (which is initially zero) by running "id <ID>"
- you have to set the ID of the modem (which is initially zero) by running ``id <ID>``
(the ID will be stored in the EEPROM of the modem, so a restart with following "id" command via MoSh should produce the previously set ID (in hex format)
......@@ -14,8 +14,8 @@ For Ubuntu, run
sudo apt install python3
sudo apt install python3-pip optional
```
For Windows (10), go to https://www.python.org/downloads/windows/ and
download the latest stable release (e.g., Python 3.8.1 from Dec. 18, 2019).
For Windows (10), go to [https://www.python.org/downloads/windows/](https://www.python.org/downloads/windows/) and
download the latest stable release (e.g., Python 3.9.2 from Feb. 19, 2021).
Make sure that you tick the box during installation that adds Python to
your system path.
Current releases of Python for Windows contain PIP already. You wil need
......@@ -57,7 +57,9 @@ environment variable PYTHONPATH with value
You have to replace the portion after the semicolon with the correct path
to your pylib folder.
!!! info "Restart applications"
Changes to the environment variables make it necessary to restart all application, which should use the new variables.
Typical this are the bash/shell and python.
## Python lib dependencies:
......
......@@ -3,25 +3,25 @@
!!! info "Under construction"
This is chapter is not finished.
To adapt the firmware to the hardware it is useful to customise the firmware. The source code contains compiler defines, which
allows the configuration during the build process.
Additional it is possible to extend with own new features. Informations are given in this tutorial to make the start easier.
In some cases you may want to adapt the firmware to your own requirements. Some options are already available to select.
This tutorial will guide you through the selectable options. Furthermore details of the firmware will be explained here,
so that you can develop own extension or modifications.
## Build Flags
The firmware has options (during compile time). Set the flags in the makefile (see "build" chapter).
Set only one option (except misc).
The source code uses c-defines to configure the behaviour during the complilation. They have to be set directly in the makefile
(see tutorial [Compile and Flash the firmware](/setup_fw/))
### Board generation
### RX/TX Board generation
!!! info "TODO"
- Which board needs which define?
The board flags have to be set matching to the attached rx/tx boards.
Choose between the following ones:
Depending ob the RX/TX board, different drivers are used. To select which ones will be included, set the defines according to the hardware.
Choose between the following ones. Only one tx and rx are allowed at the same time.
- rx-gen3:
......@@ -36,8 +36,8 @@ Choose between the following ones:
set spreading/despreading method
!!! info "TODO"
Wann sollte welche Option am besten gewählt werden?
Markiert mit (???).
Which option should be be selected in which use-case?
unclear options marked with (???).
**SPREADER_DESPREAD_BESTBIT**: only use best bit (ignore all others) (???)
......@@ -60,36 +60,40 @@ Enabled this Option is not useful in normal use.
**TXGAIN_COMP**: Enable TX gain compensation to equalize hydrophone levels.
## Add new hydrophone characteristic
## Add a new hydrophone characteristic
The firmware contains measured characteristics of some hydropphones for the automatic gain compensation.
If the type you use is not already included in the list, you can add it yourself.
The hydrophopne characteristic is stored inside the file "lut/os/fsk_24_60/gain_48x.c" in a two dimensional array.
Each entry is the attenuation of the hydrophone at a specific frequency. For the data-set fsk_24_60 the first entry is at 24 kHz.
The frequency of the next entry is increased by 1 kHz, the last is 60 kHz (together 48 steps).
The hydrophopne characteristic is stored inside the file "lut/os/fsk_24_60/gain_48x.c". A two dimensional array is used.
Each entry is the attenuation of the hydrophone at a specific frequency. For the data-set fsk_24_60 the first entry is the attenuation at 24 kHz.
The frequency of the next entry is increased by 1 kHz, the last is 60 kHz (total 49 steps).
The values are represented by scaled integers. The value 0x4000 corresponds to a attenuation of 1. At attenuation of 0.5 would be 0x2000. The minimum value is 0x0000.
The values are represented by scaled integers. The value 0x4000 corresponds to a gain of 1. A gain of 0.5 would be 0x2000. The minimum value is 0x0000.
## Change batterie levels
## Change the batterie levels
<a name="fw_batlevels"></a>
The modem firmware shows the batterie level through a LED blink code. The levels in the firmware are matched to a LiPo batterie.
The modem firmware shows the batterie level through a LED blink code. At default the levels in the firmware are matched to a LiPo batterie (3 cell).
Inside the file "batvoltage.c" the struct "batvolThresh" contains the values for the levels. The measured voltage is 200mV below the input voltage (polarity protection diode).
Inside the file "batvoltage.c" the struct "batvolThresh" contains the values for the levels. The measured voltage is 200mV below the input voltage
(reduced by the polarity protection diode).
## ahoi configuration interface (ACI)
The commands between modem and host are handled inside the ACI (ahoi configuration interface) folder in the firmware.
The ACI manages the received packets, analyses them and forward them to the function registred for that command id. This is the **command** function, which receives the attached data and
The ACI manages the received packets, analyses and forward them to the function registered for that command id. This is the **command** (cmd) function, which receives the attached data and
execute the required steps.
After this function is finished, a second function is called. This is the **response** function. In this function the data/states are collected and a response packet is build.
This packet is send back to the host by the aci.
After this function is finished, a second function is called. This is the **response** (rsp) function. In this function the data/states are collected and a response packet is build.
This packet is send back to the host by the ACI.
The managment of the packet data is done in the auto-generated files 'aci.c' and 'aci.h'. To make it easier, these files can automaticly generated with an python script.
The managment of the packet data is done in the auto-generated files "aci.c" and "aci.h". To make it easier, these files can automaticly generated with an python script.
### Commandlist
......@@ -155,7 +159,7 @@ If the parameter is not used you can use the `__attribute__ ((unused))` attribut
### Python code generator
This commandlist is read in by the python script, which generated the 'aci.c' and 'aci.h' files.
This commandlist is read by the python script, which generated the 'aci.c' and 'aci.h' files.
Depending on, which packets (files) are defined, the logic is adapted.
......@@ -197,9 +201,24 @@ The following components are already used in the firmware.
## Debugging
- Keep the compiler optimisation active -> otherwise timing problems
- Insert `asm volatile("nop");`
- Definied line in the source code which is not removed during optimisation.
- Needs only one additional clock cycle.
When you apply changes to the firmware, you might want to debug the firmware, if everything is furthermore working correct.
The hardware and software allows an in-system debugging, using the GDB with an attached programmer/debugger.
The ST-Link can be used. A common tool to connect it to the GDB is OpenOCD. Many other debuggers can also be used.
In the Internet many tutorials can be found.
During debugging, the firmware have some limits, which can result in unstable behaviour:
- Disabling the compiler optimisation
- timing problems with the interupts occure
- Sleep mode
- Debugger can lose connection*
*) Enable low power debugging. The current consumption can increase.
To set a breakpoint where the line in the cource code is optmised and not avaiable in the binary anymore, you can use
`asm volatile("nop");` to create a dummy instructed. The volatile disable the optimisation for this instruction.
The command adds (only) one additional clock cycle.
Page last revised on: {{ git_revision_date }}
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment