Skip to content

usage.md

Latest commit

 

History

History
135 lines (109 loc) · 4.57 KB

usage.md

File metadata and controls

135 lines (109 loc) · 4.57 KB

Files

src/libtrivdl.c          the library for both MCU and PC
src/libtrivdl.h          API header
examples/                examples, see below

API

You would want to make yourself familiar with shortcuts and other definitions in libtrivdl.h, because they are used extensively throughout the code.

The 'line' (struct t_line) represents a single peer-to-peer connection. It contains two 'frames', one is RX buffer, another is TX buffer. Along with frames, line has a file descriptor associated with serial port in POSIX code, flags for signalling asynchronous machine (lflags) and void pointer to arbitrary user data associated with the connection.

Each frame (struct t_frame) represents a single datalink frame (see protocol), also serving as RX or TX buffer. It has the data (all bytes from 0xBA to the end), index of next RX/TX byte and transmission synchronization flags resembling modem's RTS/CTS.

In the core sits 'asynchronous machine', which transmits and receives next byte of frame buffer when physical layer becomes ready. In between these events, when both TX and RX are busy, it calls cb_idle(). Each character is handled by incoming_char() or outgoing_char(). When they finish receiving/transmitting the entire frame, they call cb_frame_tx_done() or cb_frame_rx_done(). The main synchronization mean for all these functions is READY flag in struct t_frame, see libtrivdl.h for its description.

            library code           |    user code (callbacks)
                                   |
                                   |
                                   |   cb_frame_tx_done()
                                    /
                                   /
                   incoming_char() |
                 /                 |
  async_machine()  ------------------  cb_idle()
  or MCU ISRs                      |
  user code      \                 |
                   outgoing_char() |
                                   \
                                   |\
                                   |  cb_frame_rx_done()

Users must define three callback functions in their code: cb_frame_tx_done, cb_frame_rx_done and cb_idle. See libtrivdl.h for their prototypes. Also, asyncronous machine itself is fully implemented for POSIX side but expected to be implemented by user as interrupt service routines (ISR) for their MCU, see stream example for MSP430 implementation.

Along with core procedures, the following helper functions are provided:

  • init_frame
  • init_line
  • compute_checksum
  • add_hdr_and_checksum
  • build_frame
  • strfr (return frame as a string; only in POSIX version)
  • strfrret (return callbacks' status argument as a string; only in POSIX version)

See libtrivdl.h for details.

Build

libtrivdl provides code for both MCU and PC (aka 'POSIX' aka 'libc'). Moreover, core functions for both versions share the same C code. Source for MCU must be compiled with MCU defined:

mspgcc -DMCU ...
or:
#define MCU

while POSIX version must be built without MCU defined.

Provided makefiles build the library and examples for both Linux PC and TI MSP-EXP430G2 Launchpad with MSP430G2553 MCU on board, hopefully as simple as:

apt-get install gcc-msp430 binutils-msp430 msp430-libc
cd libtrivdl
make
# upload 'echo' example to MCU
cd examples/echo/msp430 && make upload
# initiate example transmission
../posix/echo

For debug, enable -DDEBUG in makefiles and additional callback functions in MCU code: mcudebug1 and mcudebug2 (prototypes, example). POSIX version will output debug information to stderr, while 430 Launchpad will blink green (RX) and red (TX) LED.

Examples

echo

The single synchronous ping-pong. See how compact the code using libtrivdl can be.

stream

PC (master) commands the MCU to start flooding with programmable-size frames, and starts its own flood in the opposite direction, fully two-way synchronous.

After transferring or receiving the given amount of data, master commands MCU to stop and stops itself. MCU sends statistics (rx/tx/errors) to master.

The state machine is described is stream.h.

This procedure runs multiple times using different frame sizes. At the end statistics table is printed.

You can also try to run echo master vs stream slave and vice versa.