- README, LICENSE added/updated
- headers moved to Inc
This commit is contained in:
parent
1a5ff502b3
commit
a87887a29e
21
LICENSE
Normal file
21
LICENSE
Normal file
@ -0,0 +1,21 @@
|
|||||||
|
MIT License
|
||||||
|
|
||||||
|
Copyright (c) 2021 András Wiesner
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
in the Software without restriction, including without limitation the rights
|
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||||
|
copies of the Software, and to permit persons to whom the Software is
|
||||||
|
furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in all
|
||||||
|
copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
|
SOFTWARE.
|
||||||
@ -11,7 +11,7 @@ add_library(freertos_config INTERFACE)
|
|||||||
target_include_directories(
|
target_include_directories(
|
||||||
freertos_config
|
freertos_config
|
||||||
SYSTEM INTERFACE
|
SYSTEM INTERFACE
|
||||||
Inc
|
${CMAKE_CURRENT_LIST_DIR}/../Inc
|
||||||
)
|
)
|
||||||
|
|
||||||
target_compile_definitions(freertos_config
|
target_compile_definitions(freertos_config
|
||||||
|
|||||||
297
README.md
297
README.md
@ -1,174 +1,183 @@
|
|||||||
# flexPTP
|
# EK-TM4C1294XL Connected LaunchPad flexPTP demo
|
||||||
## Flexible, low-resource IEEE1588 PTP slave-only implementation designed for MCU-based systems [implemented on TI TM4C1294 Connected LaunchPad]
|
|
||||||
|
|
||||||
### Prerequests
|
|
||||||
|
|
||||||
In order to compile the CCS project found in this repository the following tools are required:
|
## What's this?
|
||||||
|
|
||||||
- TI Code Composer Studio 9.3.0.00012 or higher,
|
> **This is a [flexPTP](https://github.com/epagris/flexPTP) demo project showcasing the capabilities of the flexPTP [IEEE 1588 Precision Time Protocol](https://ieeexplore.ieee.org/document/9120376) implementation for the [Texas Instruments EK-TM4C1294XL Connected LaunchPad](https://www.ti.com/tool/EK-TM4C1294XL) devboard.**
|
||||||
- TI TivaWare peripheral library (this package can be aquired through CCS),
|
|
||||||
- Some modification of vendor provided drivers and files (see below).
|
|
||||||
|
|
||||||
To run the project you will need:
|
Still not clear what is it useful for? No worries, it's a behind-the-scenes support technology that use unaware every day if you have a smartphone or when you are connected to the internet. Modern telecommunication and measurement systems often rely on precise time synchronization down to the nanoseconds' scale. Methods got standardized by the IEEE and now it's known by the name of the Precision Time Protocol. This software project is an evaluation environment to showcase the capabilities of our IEEE 1588 PTP implementation named `flexPTP` on the Texas Instruments EK-TM4C1294XL Connected LaunchPad board.
|
||||||
|
|
||||||
- a TI Connected LaunchPad,
|
> [!TIP]
|
||||||
- a network featuring a master clock.
|
>**Just want to try the demo and skip compiling? Download one of the precompiled binaries and jump to [Deploying](#Deploying)!**
|
||||||
|
|
||||||
### Binary image
|
|
||||||
|
|
||||||
If you don't want to compile the project for yourself, a precompiled binary can be downloaded from here. This binary image can be flashed easily using CCS.
|
### Get the sources
|
||||||
|
|
||||||
### Serial console
|
> [!NOTE]
|
||||||
|
> To acquire the full source tree after cloning the repo, please fetch the linked *submodules* as well:
|
||||||
|
|
||||||
The project is equipped with a moderately interactive command line interface accessible through the virtual serial port (e.g. `/dev/ttyACMx` on Linux) emulated by the development board. Serial port configuration: `115200-8-N-1`.
|
```
|
||||||
|
git clone https://gitea.epagris.com/epagris/flexPTP-demo-TM4C1294.git
|
||||||
|
cd flexPTP-demo-TM4C1294
|
||||||
|
git submodule init
|
||||||
|
git submodule update
|
||||||
|
```
|
||||||
|
|
||||||
After the device and software has come up, type `?` to print help, a list of terminal commands. Some commands will only be available if the Ethernet network is connected.
|
## Building
|
||||||
|
|
||||||
Sample command list:
|
### Prerequisites
|
||||||
|
|
||||||
<code>
|
The following two pieces of software are necessary for building:
|
||||||
|
- `arm-none-eabi-gcc` (v12+): the GCC ARM Cortex-M C cross-compiler
|
||||||
|
- `cmake` (v3.22+): KitWare's build management system
|
||||||
|
|
||||||
? Print this help
|
> [!NOTE]
|
||||||
|
> Both applications are available on common Linux systems through the official package repository. Although it's a Texas Instruments product, for building on Windows we recommend to install the STMicroelectronics [STM32CubeCLT](https://www.st.com/en/development-tools/stm32cubeclt.html) bundle shipping the `arm-none-eabi-{gcc|gdb}`, `openocd`. The [CMake](https://cmake.org/) needs to be installed separately.
|
||||||
|
|
||||||
|
### Compiling
|
||||||
|
|
||||||
|
The project is fully CMake managed. Configure and invoke the cross-compiler using the commands below:
|
||||||
|
|
||||||
|
```
|
||||||
|
cmake . -B build
|
||||||
|
cmake --build build --target flexptp-tiva --
|
||||||
|
```
|
||||||
|
Once the building has concluded the output binaries would be deposited in the `build` directory: `flexptp-tiva.elf`, `flexptp-tiva.bin`, `flexptp-tiva.hex`
|
||||||
|
|
||||||
|
## Deploying
|
||||||
|
|
||||||
|
### Downloading the firmware
|
||||||
|
|
||||||
|
The compiled binaries can be downloaded onto the devboard through several tools:
|
||||||
|
|
||||||
|
### Using the `lm4flash` utility
|
||||||
|
|
||||||
|
This tool is part of the open source [lm4flash](https://github.com/utzig/lm4tools) bundle, that is also available through common Linux package managers.
|
||||||
|
|
||||||
|
To program the MCU use the following command: `lm4flash build/flexptp-tiva.bin`
|
||||||
|
|
||||||
|
### Using the `openocd` application
|
||||||
|
|
||||||
|
The [OpenOCD](https://openocd.org/) programming/debugging tool can also be used to upload the firmware using the following command:
|
||||||
|
|
||||||
|
`openocd -f "board/ti_ek-tm4c1294xl.cfg" -c init -c halt -c "program build/flexptp-tiva.elf" -c exit`
|
||||||
|
|
||||||
|
OpenOCD is also available through the common Linux package managers.
|
||||||
|
|
||||||
|
### Interacting with the firmware
|
||||||
|
|
||||||
|
The firmware prints its messages to and expect user input coming on the board controller's virtual serial port using the `115200-8-N-1` configuration. Use [Putty](https://www.putty.org/) or any equivalent (e.g. GtkTerm) serial port terminal to communicate with the firmware. On Linux, the device will show up as `/dev/ttyACMx`.
|
||||||
|
|
||||||
|
> [!NOTE]
|
||||||
|
> Read the firmware's bootup hints and messages carefully!
|
||||||
|
|
||||||
|
### PPS signal
|
||||||
|
|
||||||
|
The 1PPS signal is emitted on the `PG0` pin.
|
||||||
|
|
||||||
|
## Development
|
||||||
|
|
||||||
|
An all-around [Visual Studio Code](https://code.visualstudio.com/) project is packaged along the project to enable easy development, debugging and editing. To enable these powerful features, [CMakeTools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools), [Cortex-Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug), [Embedded Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-embedded-tools) extensions and the [OpenOCD](https://openocd.org/) software package. [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) and clang-format are highly recommended.
|
||||||
|
|
||||||
|
Thas project has predefined *Launch* and *Attach* tasks.
|
||||||
|
|
||||||
|
### Software structure
|
||||||
|
|
||||||
|
The project is relying on the following large software building blocks:
|
||||||
|
- the [FreeRTOS](https://www.freertos.org/) embedded operating system,
|
||||||
|
- the [CMSIS RTOS V2](https://arm-software.github.io/CMSIS_6/latest/RTOS2/index.html) module as a wrapper for FreeRTOS,
|
||||||
|
- the [TivaWare](https://github.com/antoinealb/Tivaware) peripheral library,
|
||||||
|
- the [Lightweight IP](https://github.com/lwip-tcpip/lwip) (lwip) Ethernet stack extended with PTP timestamp support,
|
||||||
|
- the [embfmt](https://gitea.epagris.com/epagris/embfmt) a printf()-like formatted printer implementation for embedded systems.
|
||||||
|
|
||||||
|
The project is organized the following way:
|
||||||
|
|
||||||
|
```
|
||||||
|
ROOT
|
||||||
|
Drivers
|
||||||
|
CMSIS: ARM CMSIS-related files (CMSIS RTOS V2 and device headers)
|
||||||
|
tivaware: TI's peripheral library (submodule)
|
||||||
|
Inc: headers for compile-time library configuration
|
||||||
|
Middlewares: FreeRTOS CMake configuration
|
||||||
|
Modules
|
||||||
|
flexptp: our PTP implementation (submodule)
|
||||||
|
lwip: the LwIP Ethernet stack (submodule)
|
||||||
|
lwip_port: network interface and system specific implementations
|
||||||
|
embfmt: a printf()-like formatted printer implementation for embedded systems (submodule)
|
||||||
|
Src
|
||||||
|
utils: TI-provided utilities
|
||||||
|
task_eth.c: Ethernet stack management
|
||||||
|
|
||||||
|
cli.c/h: CLI-interface implementation
|
||||||
|
cmds.c: custom CLI commands
|
||||||
|
```
|
||||||
|
> [!NOTE]
|
||||||
|
> The flexPTP parameters are defined in the [flexptp_options.h](Inc/flexptp_options.h) header.
|
||||||
|
|
||||||
|
> [!NOTE]
|
||||||
|
> The low-level Ethernet network driver is located in the [tiva-tm4c129.c](Modules/lwip_port/tiva-tm4c129/netif/tiva-tm4c129.c) file.
|
||||||
|
|
||||||
|
### Printing and logging
|
||||||
|
|
||||||
|
In this project the memory-heavy `printf()` is replaced by the more embedded-optimized `MSG()` function backed by the `embfmt` library. Parameters and format specifiers are fully `printf()` compatible.
|
||||||
|
|
||||||
|
### CLI commands
|
||||||
|
|
||||||
|
The software offers you with the following multitude, most flexPTP-related of commands:
|
||||||
|
|
||||||
|
```
|
||||||
|
? Print this help (22/48)
|
||||||
|
hist Print command history
|
||||||
|
osinfo Print OS-related information
|
||||||
|
flexptp Start flexPTP daemon
|
||||||
ptp servo params [Kp Kd] Set or query K_p and K_d servo parameters
|
ptp servo params [Kp Kd] Set or query K_p and K_d servo parameters
|
||||||
|
ptp servo log internals {on|off} Enable or disable logging of servo internals
|
||||||
ptp reset Reset PTP subsystem
|
ptp reset Reset PTP subsystem
|
||||||
ptp servo offset [offset_ns] Set or query clock offset
|
ptp servo offset [offset_ns] Set or query clock offset
|
||||||
ptp log {def|corr} {on|off} Turn on or off logging
|
ptp log {def|corr|ts|info|locked|bmca} {on|off} Turn on or off logging
|
||||||
|
time [ns] Print time
|
||||||
|
ptp master [[un]prefer] [clockid] Master clock settings
|
||||||
|
ptp info Print PTP info
|
||||||
|
ptp domain [domain] Print or get PTP domain
|
||||||
|
ptp addend [addend] Print or set addend
|
||||||
|
ptp transport [{ipv4|802.3}] Set or get PTP transport layer
|
||||||
|
ptp delmech [{e2e|p2p}] Set or get PTP delay mechanism
|
||||||
|
ptp transpec [{def|gPTP}] Set or get PTP transportSpecific field (majorSdoId)
|
||||||
|
ptp profile [preset [<name>]] Print or set PTP profile, or list available presets
|
||||||
|
ptp tlv [preset [name]|unload] Print or set TLV-chain, or list available TLV presets
|
||||||
|
ptp pflags [<flags>] Print or set profile flags
|
||||||
|
ptp period <delreq|sync|ann> [<lp>|matched] Print or set log. periods
|
||||||
|
ptp coarse [threshold] Print or set coarse correction threshold
|
||||||
|
ptp priority [<p1> <p2>] Print or set clock priority fields
|
||||||
|
```
|
||||||
|
|
||||||
</code>
|
> [!TIP]
|
||||||
|
> The above hint can be listed by typing '?'.
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
> [!WARNING]
|
||||||
|
> By default, the MCU clock is sourced by the onboard (STLink) board controller on this devboard. According to our observations, this clock signal is loaded with heavy noise rendering the clock synchronization unable to settle precisely. We highly recommend to solder a 8 MHz oscillator onto the designated X3 pads to achieve the best results!
|
||||||
|
|
||||||
|
|
||||||
### Usage
|
## Related papers and references
|
||||||
|
|
||||||
To try it out, just connect the Connected LaunchPad to a live Ethernet network being connected to a master clock. After the node has established connection to the network logs and servo settings are acessible through CLI. 1PPS output is accessible on pin PG0.
|
[Time Synchronization Extension for the IO-Link Industrial Communication Protocol](https://ieeexplore.ieee.org/document/10747727)
|
||||||
|
|
||||||
### Project modules
|
[Distributed Measurement System for Performance Evaluation of Embedded Clock Synchronization Solutions](https://ieeexplore.ieee.org/document/9805958/)
|
||||||
|
|
||||||
The project is buit up from multiple modules, the following are designed to be easy to replace or modify:
|
[Portable, PTP-based Clock Synchronization Implementation for Microcontroller-based Systems and its Performance Evaluation](https://ieeexplore.ieee.org/document/9615250)
|
||||||
|
|
||||||
- servo: implementing the clock servo
|
[Synchronization of Sampling in a Distributed Audio Frequency Range Data Acquisition System Utilizing Microcontrollers](https://ieeexplore.ieee.org/document/9918455/)
|
||||||
- hw_port: containing setup functions for specific timestamp hardware
|
|
||||||
|
|
||||||
Instructions on how to replace the current modules can be found in `ptp.h`.
|
[Methods of Peripheral Synchronization in Real-Time Cyber-Physical Systems](https://ieeexplore.ieee.org/document/10178979/)
|
||||||
|
|
||||||
### Network driver modifications
|
|
||||||
|
|
||||||
Original netif driver (located in `third_party/lwip-1.4.1/ports/netif/tiva-tm4c129.c`)
|
|
||||||
has been modified so that trasmitted packets being timestamped and timestamps being written back into pbufs.
|
|
||||||
|
|
||||||
Enabling TX timestamping in `tivaif_transmit(...)`
|
|
||||||
|
|
||||||
<code>
|
|
||||||
|
|
||||||
...
|
|
||||||
|
|
||||||
pDesc->Desc.ui32CtrlStatus |= (DES0_TX_CTRL_IP_ALL_CKHSUMS | DES0_TX_CTRL_CHAINED);
|
|
||||||
|
|
||||||
<b>
|
|
||||||
|
|
||||||
#if LWIP_PTPD
|
|
||||||
pDesc->Desc.ui32CtrlStatus |= (1 << 25); // set TTSS flag
|
|
||||||
#endif
|
|
||||||
|
|
||||||
</b>
|
|
||||||
|
|
||||||
/* Decrement our descriptor counter, move on to the next buffer in the
|
|
||||||
* pbuf chain. */
|
|
||||||
ui32NumChained--;
|
|
||||||
pBuf = pBuf->next;
|
|
||||||
|
|
||||||
...
|
|
||||||
</code>
|
|
||||||
|
|
||||||
Enabling timestamp writeback in `tivaif_process_transmit(...)`
|
|
||||||
|
|
||||||
<code>
|
|
||||||
|
|
||||||
...
|
|
||||||
|
|
||||||
tDescriptorList *pDescList;
|
|
||||||
uint32_t ui32NumDescs;
|
|
||||||
|
|
||||||
<b>
|
|
||||||
|
|
||||||
#if LWIP_PTPD
|
|
||||||
struct pbuf * pPBuf;
|
|
||||||
struct tEMACDMADescriptor * pDesc;
|
|
||||||
#endif
|
|
||||||
|
|
||||||
</b>
|
|
||||||
|
|
||||||
...
|
|
||||||
|
|
||||||
</code>
|
|
||||||
|
|
||||||
|
|
||||||
<code>
|
|
||||||
|
|
||||||
/* Yes - free it if it's not marked as an intermediate pbuf */
|
## License
|
||||||
if(!((uint32_t)(pDescList->pDescriptors[pDescList->ui32Read].pBuf) & 1))
|
|
||||||
{
|
The project is created by András Wiesner (Epagris) in 2025 and published under the MIT license. Contributions are welcome! :)
|
||||||
pbuf_free(pDescList->pDescriptors[pDescList->ui32Read].pBuf);
|
|
||||||
DRIVER_STATS_INC(TXBufFreedCount);
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
<b>
|
|
||||||
|
|
||||||
#if LWIP_PTPD
|
|
||||||
pPBuf = pDescList->pDescriptors[pDescList->ui32Read].pBuf;
|
|
||||||
pDesc = &pDescList->pDescriptors[pDescList->ui32Read].Desc;
|
|
||||||
|
|
||||||
// Write timestamp back
|
|
||||||
pPBuf->time_s = pDesc->ui32IEEE1588TimeHi;
|
|
||||||
pPBuf->time_ns = pDesc->ui32IEEE1588TimeLo;
|
|
||||||
#endif
|
|
||||||
|
|
||||||
</b>
|
|
||||||
|
|
||||||
pDescList->pDescriptors[pDescList->ui32Read].pBuf = NULL;
|
|
||||||
|
|
||||||
...
|
|
||||||
|
|
||||||
</code>
|
|
||||||
|
|
||||||
Another modification has been made to enbale multicast message transmission and
|
|
||||||
reception:
|
|
||||||
|
|
||||||
(line 328:)
|
|
||||||
|
|
||||||
<code>
|
|
||||||
|
|
||||||
psNetif->flags = NETIF_FLAG_BROADCAST | NETIF_FLAG_ETHARP | NETIF_FLAG_LINK_UP <b>| NETIF_FLAG_IGMP</b>;
|
|
||||||
|
|
||||||
</code>
|
|
||||||
|
|
||||||
### UARTprintf modification
|
|
||||||
|
|
||||||
To enable task switching while waiting for new data to arrive on serial port, insert some (OS managed) delay into `UARTgets(...)` in `uartstdio.c`
|
|
||||||
|
|
||||||
<code>
|
|
||||||
|
|
||||||
...
|
|
||||||
|
|
||||||
//
|
|
||||||
// Process characters until a newline is received.
|
|
||||||
//
|
|
||||||
while(1)
|
|
||||||
{
|
|
||||||
//
|
|
||||||
// Read the next character from the receive buffer.
|
|
||||||
//
|
|
||||||
|
|
||||||
|
|
||||||
<b>
|
|
||||||
|
|
||||||
vTaskDelay(pdMS_TO_TICKS(10));
|
|
||||||
|
|
||||||
</b>
|
|
||||||
|
|
||||||
if(!RX_BUFFER_EMPTY)
|
|
||||||
{
|
|
||||||
|
|
||||||
...
|
|
||||||
|
|
||||||
</code>
|
|
||||||
@ -4,9 +4,6 @@ target_sources(
|
|||||||
|
|
||||||
main.c
|
main.c
|
||||||
|
|
||||||
flexptp_options.h
|
|
||||||
lwipopts.h
|
|
||||||
|
|
||||||
cli.c
|
cli.c
|
||||||
cli.h
|
cli.h
|
||||||
cmds.c
|
cmds.c
|
||||||
|
|||||||
@ -7,6 +7,7 @@
|
|||||||
#include "cmsis_os2.h"
|
#include "cmsis_os2.h"
|
||||||
#include "flexptp/event.h"
|
#include "flexptp/event.h"
|
||||||
#include "flexptp/logging.h"
|
#include "flexptp/logging.h"
|
||||||
|
#include "flexptp/profiles.h"
|
||||||
#include "flexptp/ptp_profile_presets.h"
|
#include "flexptp/ptp_profile_presets.h"
|
||||||
#include "flexptp/settings_interface.h"
|
#include "flexptp/settings_interface.h"
|
||||||
#include "task.h"
|
#include "task.h"
|
||||||
@ -70,6 +71,7 @@ void flexptp_user_event_cb(PtpUserEventCode uev) {
|
|||||||
switch (uev) {
|
switch (uev) {
|
||||||
case PTP_UEV_INIT_DONE:
|
case PTP_UEV_INIT_DONE:
|
||||||
ptp_load_profile(ptp_profile_preset_get(FLEXPTP_INITIAL_PROFILE));
|
ptp_load_profile(ptp_profile_preset_get(FLEXPTP_INITIAL_PROFILE));
|
||||||
|
ptp_print_profile();
|
||||||
ptp_log_enable(PTP_LOG_DEF, true);
|
ptp_log_enable(PTP_LOG_DEF, true);
|
||||||
ptp_log_enable(PTP_LOG_BMCA, true);
|
ptp_log_enable(PTP_LOG_BMCA, true);
|
||||||
break;
|
break;
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user