Indigresso Wiki

Open Source Stuff for DASH7

User Tools

Site Tools


opentag:tools:otcom

OTcom

OTcom is an officially supported, open-source client-side tool for developers working with OpenTag. OTcom was originally developed by Wizzilab, and they continue to lead the development effort. At the most basic level, it provides a cross-platform, Qt-based GUI that implements a TTY MPipe interface between client and server. Additional features include NDEF wrapper support and Message API input support.

OTcom source code and documentation are currently hosted on the OpenTag sourceforge site.
OTcom git repository
OpenTag sourceforge project home

Databrief

OTcom Program Overview
Last Release 2.0214, 14 February 2012
Repository OTcom git repository
Features Overview
Com Interfaces TTY (POSIX), COM (Windows), USB-CDC
Default TTY Speed 115200 baud
Data Interfaces Text, Raw Binary, NDEF with text payload
I/O Features Logging server output, sending client input (API messages) to server
GUI Features Terminal window with selectable controls
MPipe MAC Support Full: Acknowledging, CRC validation, Sequence ID
Bonus MAC Features OTcom socket control
Platform & Framework Attributes
Development Library Qt Framework
Development Tools Qt Creator IDE
Programming Languages C, C++
Target Platforms Linux, Mac, Windows

Building for Linux/POSIX

These build instructions assume a Linux/POSIX command line host.

Quickstart

Get source

git clone git://opentag.git.sourceforge.net/gitroot/opentag/OTcom

Build

qmake && make

Real clean

make clean && rm Makefile && qmake && make clean && make

Run

../bin/otcom

Make tags

ctags . *

Detailed Build Instructions

Build & Install

Get source from SourceForge

git clone git://opentag.git.sourceforge.net/gitroot/opentag/OTcom

QT4 & Ruby
Verify that C++ compiler is installed

g++ -v

(if not)

sudo aptitude install build-essential

For rpm-based distribution

yum install gcc-c++

Install Qt4 development tools

sudo apt-get install libqt4-dev libqt4-qt3support

For rpm-based distribution

yum install qt-devel

Qt3 conflicts with Qt4 so remove it if it is already installed

sudo apt-get remove qt3-dev-tools

Add usb support for Ruby (but should be removed later)

sudo apt-get install libusb-dev

For rpm-based distribution

yum install libusb-devel

Build OTcom

configure using qmake (no output to this command). Other distributions may have qmake4 or qmake-qt4

qmake 

make otcom

make

tricky rebuild : needed when changing some header files names or content that are used by the qmake preprocessor

make clean && rm Makefile && qmake && make clean && make

the binary is created in

../bin/otcom

Create mapping for com ports

For the particular case of the virtual com through a FTDI chip, a symbolic link should be made for each USB port. By default the commap directory should be placed in /usr. It is possible to change the default commap path to whatever you want in file otcConfig.h.

mkdir /usr/commap
ln -s /dev/ttyUSB0 /usr/commap/com0
ln -s /dev/ttyUSB1 /usr/commap/com1
ln -s /dev/ttyUSB2 /usr/commap/com2
...
ln -s /dev/ttyUSBX /usr/commap/comX

launch OTCom

../bin/otcom

Building with Qt Creator on Mac

To be completed.

Building Qt

Building OTcom

Building with Qt Creator on Windows

To build OTcom for Windows requires some extra steps. For one thing, the system of DLLs in Windows is byzantine, so if you want your app to be portable at all, it will need to be statically linked. Unfortunately, this is easier said than done, because in order to build statically linked apps with Qt, you first need to build Qt itself with the “static” parameter enabled. Fortunately, though, Qt has a good tutorial how to do this (Todo: add link). After you build Qt and have Qt Creator running, the build process is identical to using Qt Creator on the Mac (see that article).

MinGW vs. MSVC

Some people may want to use MinGW, but JP highly recommends using MSVC Express 2008 (Todo: add link) instead of MinGW. MSVC Express is from MS, so it is obviously not open source, but it IS freeware. MSVC has an easy download-install process, and after that it “just works.” The same cannot be said of MinGW, which can get obfuscated by having multiple installations. In addition, MSVC does not require that the MinGW libraries get compiled into the app, so it is a bit more efficient. You will need to download MSVC Express in order to build Qt, unless of course you already have the payware version of MSVC installed, or unless you decide to use MinGW.

Usage

The purpose of the tool is to read and write packets over the com port. Another program can connect to OTCom over a socket using the OTC protocol (see below) and thus communicate with the OT stack through the OTCom An NDEF packets parser & OT packets parser are implemented to suit the need to communicate with an OT stack over an UART.

Print Mode Description
None No incoming data is displayed in the OTCom window.
Raw Prints data received over the serial port as is (no formatting)
NDEF + OT - Considers the packet has a valid NDEF format of the subset used by OT
- Header can be only 0xDD, 0xBD, 0x36 or 0x56, type length is 0, id length when available is 2.
- Displays in format [seq nb] [id] [data]
- If the CRC fails the packet is colored in red. This mode supports chunking

Establish Communication

  1. Launch OTCom
  2. Select com port, baud rate & flow control mode from the user interface.
  3. Select print mode (none, raw, NDEF parser enabled or NDEF+OT parsers enabled). Whatever the print mode, data received over the com port is piped to the socket, and data received over the socket from another program is piped to the com port.

Socket

OTCom opens a server, so that other programs program can connect to OTCom over a socket using the OTC protocol (see below) and thus communicate with the OT stack through the OTCom. Raw data received over the com port is piped to the socket, and data received over the socket from another program is piped to the com port as is (except for the OTC protocol header).

Command Prompt

A command prompt is available in the OTCom GUI. The following commands can be interpreted.

Command Description Syntax (1)
:S Print otcom status :S
:EL Toggle local echo :EL
:ER Toggle remote echo (2) :ER
:V Toggle verbose mode :V
OT ALP null template (null command) OT
OT? ALP null with ACK (ping target) OT?
OT+R Read file data OT+R <filetype> <id_a>,[off],[len] <id_b>,[off],[len] …
OT+RA Read file header and data (read all) OT+RA <filetype> <id_a>,[off],[len] <id_b>,[off],[len] …
OT+RP Read file permissions OT+RP <filetype> <id_a> <id_b> …
OT+RH Read file header OT+RH <filetype> <id_a> <id_b> …
OT+DEL Delete file without ACK OT+DEL <filetype> <id_a> <id_b> …
OT+DEL? Delete file with ACK OT+DEL? <filetype> <id_a> <id_b> …
OT+NEW Create new file without ACK OT+NEW <filetype> <id_a> <id_b> …
OT+NEW? Create new file with ACK OT+NEW? <filetype> <id_a> <id_b> …
OT+DEF Restore to default value without ACK OT+DEF <filetype> <id_a> <id_b> …
OT+DEF? Restore to default value with ACK OT+DEF? <filetype> <id_a> <id_b> …
OT+W Write data to file without ACK OT+W <filetype> <id_a>,[off],[len] <data> <id_b>,[off],[len] <data> …
OT+W? Write data to file with ACK OT+W? <filetype> <id_a>,[off],[len] <data> <id_b>,[off],[len] <data> …
OT+WP Write permissions to file without ACK OT+WP <filetype> <id_a> <perm> <id_b> <perm> …
OT+WP? Write permissions to file with ACK OT+WP? <filetype> <id_a> <perm> <id_b> <perm> …
Raw ALP commands
ALP Raw ALP command RAW <alp_id>,<alp_cmd> <Bintex>
ALP_ Raw ALP command, postponed processing RAW_ <alp_id>,<alp_cmd> <Bintex>
ALP? Raw ALP command with ACK RAW? <alp_id>,<alp_cmd> <Bintex>

(1) numbers are in hexadecimal
(2) echo bit in the command is interpreted on the target, available on the WL branch

As defined in the Mode 2 Filedata ALP
<filetype> : GFB, ISFB, ISFSB
<id> : file index
[off] : start read/write offset in the file (optional, default 0)
[len] :read/write length (optional, default 0 = read/write all)
<data> : data to be written in the file
<perm> : permission byte
<Bintex> : raw data expressed in Bintex format

When using ALP_ (or other underscore commands), the NDEF Message End flag is not asserted. The server will store the command (record) in its command buffer, and it will not process the commands in the buffer until a command is received with the Message End flag asserted.

OTC Protocol

OTC protocol consists, of a simple header :

  • 1 byte sync word
  • 2 byte size
  • 1 byte packet type code
  • N byte payload
sync size (hi) size (lo) packet type pload (0) pload (N-1)

The following packet types are currently supported :

Code Meaning
OTC_PROTOCOL_BAUDRATE_CHANGE_REQUEST Change baud Rate to value contained in the payload
OTC_PROTOCOL_RECONNECT_COM_PORT Reconnect com port
OTC_PROTOCOL_KILL_OTC Kill OTCom
OTC_PROTOCOL_STATUS Request status
OTC_PROTOCOL_STATUS_RESULT Give status
OTC_PROTOCOL_SEND_AS_IS Send payload over com port
OTC_PROTOCOL_RAW_DATA Send raw data over the socket (as payload)

Versioning

The following format is used : Y.MMDD (ex. version of Feb 14, 2012 is 2.0214). Version number is automatically generated at compile time. If the source code is part of a git repository, the date of the commit is used. Else, the compilation date is used.

Planned Features

In the near future OTcom will gain GUI features for more easily uploading and downloading the DASH7 registry files stored in the OpenTag file system. These registry files are very important for configuring an OpenTag device's features during runtime, such as channel support, power levels, duty cycles, addresses, etc (basically everything).

opentag/tools/otcom.txt · Last modified: 2013/05/28 14:46 by jpnorair