Skip to content
This repository has been archived by the owner on Jan 7, 2024. It is now read-only.

Commit

Permalink
termiWin 1.2.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@veeso
veeso committed Dec 21, 2019
1 parent 8b7a2fe commit 1bb048b
Showing 1 changed file with 134 additions and 70 deletions.
204 changes: 134 additions & 70 deletions README.md
100755 → 100644
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,80 @@
# termiWin

[![HitCount](http://hits.dwyl.io/ChristianVisintin/termiWin.svg)](http://hits.dwyl.io/ChristianVisintin/termiWin) [![Stars](https://img.shields.io/github/stars/ChristianVisintin/termiWin.svg)](https://github.com/ChristianVisintin/termiWin) [![Issues](https://img.shields.io/github/issues/ChristianVisintin/termiWin.svg)](https://github.com/ChristianVisintin/termiWin) [![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/ChristianVisintin/termiWin/issues)
[![HitCount](http://hits.dwyl.io/ChristianVisintin/termiWin.svg)](http://hits.dwyl.io/ChristianVisintin/termiWin) [![Stars](https://img.shields.io/github/stars/ChristianVisintin/termiWin.svg)](https://github.com/ChristianVisintin/termiWin) [![Issues](https://img.shields.io/github/issues/ChristianVisintin/termiWin.svg)](https://github.com/ChristianVisintin/termiWin) [![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/ChristianVisintin/termiWin/issues) [![Build](https://api.travis-ci.org/ChristianVisintin/termiWin.svg?branch=master)](https://github.com/ChristianVisintin/termiWin)

~ A termios porting for Windows ~

Current Version 1.1.4 (03/11/2018)
Current Version 1.2.0 (21/12/2019)

- [termiWin](#termiwin)
- [Introduction](#introduction)
- [Implementation](#implementation)
- [Supported Build Platform](#supported-build-platform)
- [Library Architecture](#library-architecture)
- [The termios Structure](#the-termios-structure)
- [Input modes flags](#input-modes-flags)
- [Local modes flags](#local-modes-flags)
- [Control modes flags](#control-modes-flags)
- [Output modes flags](#output-modes-flags)
- [Special character array](#special-character-array)
- [Serial configuration functions](#serial-configuration-functions)
- [Int tcgetattr(int fd, struct termios *termios_p)](#int-tcgetattrint-fd-struct-termios-termiosp)
- [int tcsetattr(int fd, int optional_actions, struct termios *termios_p)](#int-tcsetattrint-fd-int-optionalactions-struct-termios-termiosp)
- [int tcsendbreak(int fd, int duration)](#int-tcsendbreakint-fd-int-duration)
- [int tcdrain(int fd)](#int-tcdrainint-fd)
- [Int tcflush(int fd, int queue_selector)](#int-tcflushint-fd-int-queueselector)
- [Int tcflow(int fd, int action)](#int-tcflowint-fd-int-action)
- [Void cfmakeraw(struct termios *termios_p)](#void-cfmakerawstruct-termios-termiosp)
- [speed_t cfgetispeed(const struct termios *termios_p)](#speedt-cfgetispeedconst-struct-termios-termiosp)
- [speed_t cfgetospeed(const struct termios *termios_p)](#speedt-cfgetospeedconst-struct-termios-termiosp)
- [int cfsetispeed(struct termios *termios_p, speed_t speed)](#int-cfsetispeedstruct-termios-termiosp-speedt-speed)
- [int cfsetospeed(struct termios *termios_p, speed_t speed)](#int-cfsetospeedstruct-termios-termiosp-speedt-speed)
- [int cfsetsspeed(struct termios *termios_p, speed_t speed)](#int-cfsetsspeedstruct-termios-termiosp-speedt-speed)
- [Supported speed](#supported-speed)
- [Serial transmission/receiving - open/close Functions](#serial-transmissionreceiving---openclose-functions)
- [Int openSerial(char- portname, int opt)](#int-openserialchar--portname-int-opt)
- [Int closeSerial(int fd)](#int-closeserialint-fd)
- [Int writeToSerial(int fd, char- buffer, int count)](#int-writetoserialint-fd-char--buffer-int-count)
- [Int readFromSerial(int fd, char- buffer, int count)](#int-readfromserialint-fd-char--buffer-int-count)
- [Int selectSerial(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout)](#int-selectserialint-nfds-fdset-readfds-fdset-writefds-fdset-exceptfds-struct-timeval-timeout)
- [HANDLE getHandle()](#handle-gethandle)
- [Multiple serial communications](#multiple-serial-communications)
- [What is termiWin intended for](#what-is-termiwin-intended-for)
- [Contributions](#contributions)
- [Is termiWin still supported](#is-termiwin-still-supported)
- [Changelog](#changelog)
- [1.2.0 (21.12.2019)](#120-21122019)
- [License](#license)

## Introduction

termiWin is a library which purpose is to allow you to use on a Windows system, the same code used in Linux to communicate with a device through a serial port.
This is possible because termios’s functions have been rewritten to be compatible with Windows’s COM functions.

## Implementation

It's enough to include termios.h, termiWin.h and termiWin.c to build the project. You don't have to change anything else in your code

## Supported Build Platform

- **Visual C++** (> 12.0)
- Build and works fine without any restriction
- **Visual C++** (< 12.0)
- Not tested, if you want you can report a working build on an older compiler. I will appreciate your contribution.
- **MinGW**
- Requires ```-D TERMIWIN_DONOTREDEFINE``` to build (which means that open, close, select etc must be replaced with openSerial, closeSerial, ...), but works fine afterall and it's used on my travis configuration

## Library Architecture

### The termios Structure

This is the main structure of the library and it’s often passed as argument to the functions, it has the following members:

* tcflag_t c_iflag; /\*input modes\*/
* tcflag_t c_oflag; /\*output modes\*/
* tcflag_t c_cflag; /\*control modes\*/
* tcflag_t c_lflag; /\*local modes\*/
* cc_t c_cc[NCCS]; /\*special character\*/
- tcflag_t c_iflag; /\*input modes\*/
- tcflag_t c_oflag; /\*output modes\*/
- tcflag_t c_cflag; /\*control modes\*/
- tcflag_t c_lflag; /\*local modes\*/
- cc_t c_cc[NCCS]; /\*special character\*/

where tcflag_t is defined as an unsigned integer.

Expand All @@ -30,51 +83,51 @@ There five types of flags, sorted by mode; they are implemented in the same way

#### Input modes flags

* INPCK – Not implemented, use PARENB instead.
* IGNPAR – Not implemented, disable PARENB instead.
* PARMRK – Not implemented, use PARENB instead.
* ISTRIP – Not implemented, use CS7 instead.
* IGNBRK – Not implemented.
* IGNCR – Not implemented.
* ICRNL – Not implemented.
* INLCR – Not implemented.
* IXOFF - If this bit is set, start/stop control on input is enabled. In other words, the computer sends STOP and START characters as necessary to prevent input from coming in faster than programs are reading it. The idea is that the actual terminal hardware that is generating the input data responds to a STOP character by suspending transmission, and to a START character by resuming transmission.
* IXON - If this bit is set, start/stop control on output is enabled. In other words, if the computer receives a STOP character, it suspends output until a START character is received. In this case, the STOP and START characters are never passed to the application program. If this bit is not set, then START and STOP can be read as ordinary characters.
- INPCK – Not implemented, use PARENB instead.
- IGNPAR – Not implemented, disable PARENB instead.
- PARMRK – Not implemented, use PARENB instead.
- ISTRIP – Not implemented, use CS7 instead.
- IGNBRK – Not implemented.
- IGNCR – Not implemented.
- ICRNL – Not implemented.
- INLCR – Not implemented.
- IXOFF - If this bit is set, start/stop control on input is enabled. In other words, the computer sends STOP and START characters as necessary to prevent input from coming in faster than programs are reading it. The idea is that the actual terminal hardware that is generating the input data responds to a STOP character by suspending transmission, and to a START character by resuming transmission.
- IXON - If this bit is set, start/stop control on output is enabled. In other words, if the computer receives a STOP character, it suspends output until a START character is received. In this case, the STOP and START characters are never passed to the application program. If this bit is not set, then START and STOP can be read as ordinary characters.

#### Local modes flags

Since there’s no way to implement them in Windows, they have asbolutely no effect using termiWin, but you can keep the same you use in Linux for compatibilty.

#### Control modes flags

* CSTOPB - If this bit is set, two stop bits are used. Otherwise, only one stop bit is used.
* PARENB - If this bit is set, generation and detection of a parity bit are enabled.
* PARODD - This bit is only useful if PARENB is set. If PARODD is set, odd parity is used, otherwise even parity is used.
* CSIZE - This is a mask for the number of bits per character.
* CS5 - This specifies five bits per byte.
* CS6 – This specifies six bits per byte.
* CS7 – This specifies seven bits per byte.
* CS8 – This specifies eight bits per byte.
* CLOCAL – Is used in termios for ignoring the data carrier detected, but in Windows it can't be implemented
* CREAD – In termios, if not set, no character will be received, but in Windows it can't be implemented
- CSTOPB - If this bit is set, two stop bits are used. Otherwise, only one stop bit is used.
- PARENB - If this bit is set, generation and detection of a parity bit are enabled.
- PARODD - This bit is only useful if PARENB is set. If PARODD is set, odd parity is used, otherwise even parity is used.
- CSIZE - This is a mask for the number of bits per character.
- CS5 - This specifies five bits per byte.
- CS6 – This specifies six bits per byte.
- CS7 – This specifies seven bits per byte.
- CS8 – This specifies eight bits per byte.
- CLOCAL – Is used in termios for ignoring the data carrier detected, but in Windows it can't be implemented
- CREAD – In termios, if not set, no character will be received, but in Windows it can't be implemented

#### Output modes flags

Since there’s no way to implement them in Windows, they have asbolutely no effect using termiWin, but you can keep the same you use in Linux for compatibilty.

#### Special character array

* VEOF – Is the EOF character to be used during the communication.
* VEOL – Not implemented.
* VERASE – Not implemented.
* VINTR – Interrupt character.
* VKILL – Not implemented.
* VMIN – If set to 0, the port is set to not-blocking, otherwise to blocking.
* VQUIT – Not implemented.
* VSTART – Not implemented.
* VSTOP – Not implemented.
* VSUSP – Not implemented.
* VTIME – Timeout for reading operations when COM is set to not-blocking.
- VEOF – Is the EOF character to be used during the communication.
- VEOL – Not implemented.
- VERASE – Not implemented.
- VINTR – Interrupt character.
- VKILL – Not implemented.
- VMIN – If set to 0, the port is set to not-blocking, otherwise to blocking.
- VQUIT – Not implemented.
- VSTART – Not implemented.
- VSTOP – Not implemented.
- VSUSP – Not implemented.
- VTIME – Timeout for reading operations when COM is set to not-blocking.

### Serial configuration functions

Expand Down Expand Up @@ -104,30 +157,30 @@ Returns 0 if succeded, otherwise -1.

Discards data on serial port. queue_selector can assume the following values:

* TCIFLUSH (discards data received but still not read).
* TCOFLUSH (discards data written but still not transmitted),
* TCIOFLUSH (discards both data received but still not read and data written but still not transmitted).
- TCIFLUSH (discards data received but still not read).
- TCOFLUSH (discards data written but still not transmitted),
- TCIOFLUSH (discards both data received but still not read and data written but still not transmitted).

Returns 0 if succeded, otherwise -1.

#### Int tcflow(int fd, int action)

Suspends transmission or receptions of data on serial port based on action. Action can assume the following values:

* TCOON restarts suspended output.
* TCIOFF transmits a STOP character.
* TCION transmits a START character.
* TCOOF suspends output.
- TCOON restarts suspended output.
- TCIOFF transmits a STOP character.
- TCION transmits a START character.
- TCOOF suspends output.

Returns 0 if succeded, otherwise -1.

#### Void cfmakeraw(struct termios \*termios_p)

Sets but doesn’t commit the following options for the serial port:

* Charset: 8 bits
* StopBits: one stop bit
* Parity: no parity
- Charset: 8 bits
- StopBits: one stop bit
- Parity: no parity

Use tcsetattr to commit them.

Expand Down Expand Up @@ -162,17 +215,17 @@ Use tcsetattr to commit them.

The supported speeds are the the following (not all speeds could be implemented since some of them can't be used in a Windows environment)

* B110
* B300
* B600
* B1200
* B2400
* B4800
* B9600
* B19200
* B38400
* B57600
* B115200
- B110
- B300
- B600
- B1200
- B2400
- B4800
- B9600
- B19200
- B38400
- B57600
- B115200

### Serial transmission/receiving - open/close Functions

Expand All @@ -182,7 +235,7 @@ The supported speeds are the the following (not all speeds could be implemented
#define TERMIWIN_DONOTREDEFINE
```

#### Int openSerial(char* portname, int opt)
#### Int openSerial(char- portname, int opt)

Open the serial port which name is portname with opt set for the port to be read only, write only or both read/write (O_RDONLY,
O_WRONLY, O_RDWR). Returns the file descriptor (fd is actually useless in Windows with serial ports, but is set for
Expand All @@ -194,13 +247,13 @@ The portname must be in the format "COMnumber" (e.g. COM2, COM11).
Closes the serial port.
Returns 0 if succeded, otherwise -1. The function can be called using close instead of closeSerial. (for termios compatibilty).

#### Int writeToSerial(int fd, char* buffer, int count)
#### Int writeToSerial(int fd, char- buffer, int count)

Writes to serial “count” characters contained in buffer.
Returns the number of transmitted characters or -1 if transmission failed.
The function can be called using write instead of writeToSerial (for termios compatibilty).

#### Int readFromSerial(int fd, char* buffer, int count)
#### Int readFromSerial(int fd, char- buffer, int count)

Reads “count” bytes from serial port and put them into buffer.
Returns the number of read bytes or -1 if read failed.
Expand All @@ -226,17 +279,17 @@ At the moment is not possible to have more than one serial communication at the

termiWin is just a simple library which executes termios functions using Windows libsock functions, because of that, any particular behaviour in the communication with the serial device, could not work properly. **termiWin is intended just for simple communications**.

When termiWin *can be* a good choice? ✅
When termiWin *can be- a good choice? ✅

* ✅ - When you have to do a quick project without particular requirements.
* ✅ - When you don't need performance and high reliability.
* ✅ - When the communication between you and the serial device doesn't require a particular configuration.
- ✅ - When you have to do a quick project without particular requirements.
- ✅ - When you don't need performance and high reliability.
- ✅ - When the communication between you and the serial device doesn't require a particular configuration.

When termiWin **Is NOT** a good choice? ❌
When termiWin **Is NOT*- a good choice? ❌

* ❌ - When you need multiple device communications. termiWin just doesn't support this feature at the moment.
* ❌ - When you need performance - since termiWin has to convert termios to windows instructions, it won't be faster than a program with windows instructions wrote by the developer.
* ❌ - When you require particular configuration and to use particular functions (such as tcdrain, tcflush etc) - they could work, but I can't assure
- ❌ - When you need multiple device communications. termiWin just doesn't support this feature at the moment.
- ❌ - When you need performance - since termiWin has to convert termios to windows instructions, it won't be faster than a program with windows instructions wrote by the developer.
- ❌ - When you require particular configuration and to use particular functions (such as tcdrain, tcflush etc) - they could work, but I can't assure

---

Expand All @@ -248,6 +301,17 @@ Everybody can contribute to this project, indeed any improvement will be appreci

Well, I'm not working on it anymore, but I will answer to your questions and I will submit pull requests if they can be an improvement to the library.

## Changelog

### 1.2.0 (21.12.2019)

- Don't build on Linux/MacOS
- Termios header
- Fixed ifndef in termiWin.h
- Added strncat_s to build on Visual Studio without enabling unsafe code
- Added termiWin version macros (TERMIWIN_VERSION, TERMIWIN_MAJOR_VERSION, TERMIWIN_MINOR_VERSION)
- Added travis-CI.yml to project

## License

termiWin is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as
Expand Down

0 comments on commit 1bb048b

Please sign in to comment.