Skip to content

Commit 94d0391

Browse files
MqxxKatze719
Mqxx
authored and
Katze719
committed
Update README.md
1 parent 1057698 commit 94d0391

File tree

1 file changed

+100
-104
lines changed

1 file changed

+100
-104
lines changed

‎README.md‎

Lines changed: 100 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,19 @@
1+
<!-- Badges -->
2+
[Build Win32 DLL]: https://img.shields.io/github/actions/workflow/status/TypeScriptPlayground/Serial/build_windows.yml?label=Build%20Win32%20DLL&labelColor=343b42&logo=github&logoColor=959DA5 'Win32 Build'
3+
[Build Linux SO]: https://img.shields.io/github/actions/workflow/status/TypeScriptPlayground/Serial/build_linux.yml?label=Build%20Linux%20SO&labelColor=343b42&logo=github&logoColor=959DA5 'Linux Build'
4+
[Release Downloads]: https://img.shields.io/github/downloads/TypeScriptPlayground/Serial/total?label=Downloads%20&labelColor=343b42&logo=docusign&logoColor=959DA5 'Total Release Downloads'
5+
16
# Serial
2-
[![Build Win32 DLL](https://img.shields.io/github/actions/workflow/status/TypeScriptPlayground/Serial/build_windows.yml?label=Build%20Win32%20DLL&labelColor=343b42&logo=github&logoColor=959DA5)](https://github.com/TypeScriptPlayground/Serial/actions/workflows/build_windows.yml)
3-
[![Build Linux SO](https://img.shields.io/github/actions/workflow/status/TypeScriptPlayground/Serial/build_linux.yml?label=Build%20Linux%20SO&labelColor=343b42&logo=github&logoColor=959DA5)](https://github.com/TypeScriptPlayground/Serial/actions/workflows/build_linux.yml)
4-
[![Releases Downloads](https://img.shields.io/github/downloads/TypeScriptPlayground/Serial/total?label=Downloads%20&labelColor=343b42&logo=docusign&logoColor=959DA5)](https://github.com/TypeScriptPlayground/Serial/releases)
7+
[![Build Win32 DLL]](https://github.com/TypeScriptPlayground/Serial/actions/workflows/build_windows.yml)
8+
[![Build Linux SO]](https://github.com/TypeScriptPlayground/Serial/actions/workflows/build_linux.yml)
9+
[![Release Downloads]](https://github.com/TypeScriptPlayground/Serial/releases)
510

611
<a href="https://deno.land"><img align="right" src="https://deno.land/logo.svg" height="150px" alt="the deno mascot dinosaur standing in the rain"></a>
712

813
A [serial](https://en.wikipedia.org/wiki/Serial_communication) library written in TypeScript for [Deno](https://deno.land) without any third party modules.
914

1015
This library provides an interface for the communication with serial devices and **doesn't use any third party modules**. It uses C++ functions which are included in a [dynamic link library](https://de.wikipedia.org/wiki/Dynamic_Link_Library) or [shared object](https://en.wikipedia.org/wiki/Library_(computing)#Shared_libraries). These functions are then loaded by deno to establish a serial connection and talk to the devices.
1116

12-
A big thanks goes out to [@Katze719](https://github.com/Katze719) who wrote most of the C++ files and functions!
13-
1417
<br>
1518

1619
> <picture>
@@ -20,7 +23,7 @@ A big thanks goes out to [@Katze719](https://github.com/Katze719) who wrote most
2023
>
2124
> This library and the documentation are still work in progress!
2225
23-
### Features
26+
## Features
2427
- Communication with serial devices.
2528
- Create multiple serial connections at the same time.
2629
- List available ports and their properties.
@@ -29,129 +32,113 @@ A big thanks goes out to [@Katze719](https://github.com/Katze719) who wrote most
2932
- Uses no third party modules.
3033
- Works on different operating systems (check [compatibility](#compatibility) for mor info).
3134

32-
### Compatibility
33-
- [x] Windows (implemented)
34-
- [ ] Linux (in progress)
35+
## Compatibility
36+
| OS | Tested version | Current state |
37+
|---------|------------------|---------------|
38+
| Windows | Windows 10 (x64) | implemented |
39+
| Linux | - | in progress |
3540

36-
### Possible/Known issues
41+
## Possible/Known issues
3742
- What happens if you open multiple connections from the same instance.
3843
- Every function returns the status code although it is previously checked.
3944
- What happens if you async read 2 times directly after each other.
4045
- Linux write currently not working
4146

42-
### Usage
43-
#### `class` Serial
47+
## Examples - How to use
48+
### Ports
49+
Get a list with all serial ports and their info that are currently available on your system.
50+
51+
`main.ts`
4452
```typescript
45-
/**
46-
* Create a new instance of a serial connection.
47-
*/
48-
new Serial()
49-
```
53+
import { Serial } from "./mod.ts";
5054

51-
<br>
55+
// create new instance of a serial object
56+
const serial = new Serial();
5257

53-
#### `getter property` Serial.isOpen
54-
```typescript
55-
/**
56-
* Get the current connection status of the serial connection.
57-
* @returns {boolean} Returns `true` if the serial connection is open, otherwise returns `false`
58-
*/
59-
get isOpen() : boolean
58+
// get all available ports
59+
const availablePorts = serial.getPortsInfo();
60+
61+
// console log the list
62+
console.log(availablePorts);
6063
```
6164

62-
<br>
65+
> Example output:
66+
> ```
67+
> [
68+
> { name: 'COM1' },
69+
> { name: 'COM2' },
70+
> ...
71+
> { name: 'tty/USB1' }
72+
> ]
73+
> ```
6374
64-
#### `methode` Serial.open()
75+
### Sending
76+
Send data to a serial device. For exampe to an [Arduino](https://www.arduino.cc/).
77+
78+
`main.ts`
6579
```typescript
66-
/**
67-
* Opens the serial connection.
68-
* @param {string} port The port to connect
69-
* @param {number} baudrate The baudrate
70-
* @param {SerialOptions} serialOptions Additional options for the serial connection (`data bits`, `parity`, `stop bits`)
71-
* @returns {number} The status code
72-
*/
73-
open(
74-
port : string,
75-
baudrate : number,
76-
serialOptions? : SerialOptions
77-
) : number
78-
```
80+
import { Serial } from "./mod.ts";
7981
80-
<br>
82+
// create new instance of a serial object
83+
const serial = new Serial();
8184
82-
#### `methode` Serial.close()
83-
```typescript
84-
/**
85-
* Closes the serial connection.
86-
*/
87-
close() : number
88-
```
85+
// open the connection
86+
serial.open();
8987
90-
<br>
88+
// encode the message to a Uint8Array
89+
const textToSend = 'Hello from TypeScript!'
90+
const encodedTextToSend = new TextEncoder().encode(textToSend)
9191
92-
#### `methode` Serial.read()
93-
```typescript
94-
/**
95-
* Read data from serial connection.
96-
* @param {Uint8Array} buffer Buffer to read the bytes into
97-
* @param {number} bytes The number of bytes to read
98-
* @param {number} timeout The timeout in `ms`
99-
* @param {number} multiplier The timeout between reading individual bytes in `ms`
100-
* @returns {number} Returns number of bytes read
101-
*/
102-
read(
103-
buffer : Uint8Array,
104-
bytes : number,
105-
timeout = 0,
106-
multiplier = 10
107-
) : number
92+
// send the message
93+
serial.send(encodedTextToSend, encodedTextToSend.length);
10894
```
10995
110-
<br>
96+
### Reading
97+
Read data from a serial device. Again, in our example from an Arduino.
98+
> Depending on your Arduino board you may need to press the reset button on the board after uploading the sketch, in order to receive data.
11199
112-
#### `methode` Serial.readUntil()
113-
```typescript
114-
/**
115-
* Read data from serial connection until a linebreak (`\n`) gets send.
116-
* @param {Uint8Array} buffer Buffer to read the bytes into
117-
* @param {number} bytes The number of bytes to read
118-
* @param {number} timeout The timeout in `ms`
119-
* @param {number} multiplier The timeout between reading individual bytes in `ms`
120-
* @param {string} searchString A string to search for
121-
* @returns {number} Returns number of bytes read
122-
*/
123-
readUntil(
124-
buffer : Uint8Array,
125-
bytes : number,
126-
timeout = 0,
127-
multiplier = 10,
128-
searchString = '',
129-
) : number
130-
```
100+
`sketch.ino`
101+
```ino
102+
void setup() {
103+
Serial.begin(9600);
104+
while (!Serial) {
105+
;
106+
}
107+
}
131108

132-
<br>
109+
void loop() {
110+
Serial.println("Hello from Arduino!");
111+
}
112+
```
133113

134-
#### `methode` Serial.write()
114+
`main.ts`
135115
```typescript
136-
/**
137-
* Write data to serial connection.
138-
* @param {Uint8Array} buffer The data to write/send
139-
* @param {number} bytes The number of bytes to read
140-
* @param {number} timeout The timeout in `ms`
141-
* @param {number} multiplier The timeout between reading individual bytes in `ms`
142-
* @returns {number} Returns number of bytes written
143-
*/
144-
write(
145-
buffer : Uint8Array,
146-
bytes : number,
147-
timeout = 0,
148-
multiplier = 10
149-
) : number
150-
```
116+
import { Serial } from "./mod.ts";
151117

152-
<br>
118+
// create new instance of a serial object
119+
const serial = new Serial();
120+
121+
// open the connection
122+
serial.open();
123+
124+
// create a new buffer to store incoming bytes,
125+
// in this example we want to read a maximum of 100 bytes
126+
const bufferToRead = new Uint8Array(100);
127+
128+
// read data into the buffer
129+
serial.read(bufferToRead, bufferToRead.length);
130+
131+
// decode the data from the buffer
132+
const decodedTextToRead = new TextDecoder().decode(bufferToRead);
153133

154-
### Examples
134+
// console log the text
135+
console.log(decodedTextToRead);
136+
```
137+
138+
> Example output:
139+
> ```
140+
> Hello from Arduino!
141+
> ```
155142
156143
WIP
157144
@@ -205,3 +192,12 @@ void loop() {
205192
}
206193
}
207194
```
195+
## Credits
196+
197+
- Big thanks goes out to [@Katze719](https://github.com/Katze719) who wrote most of the C++ files and functions!
198+
- Thanks to [@AapoAlas](https://github.com/aapoalas) for the great support and help on the [Deno Discord](https://discord.gg/deno)!
199+
200+
## Licence
201+
Apache-2.0. Check [LICENSE](./LICENSE) for more details. Feel free to contribute to this project.
202+
203+
Copyright 2023 © Max

0 commit comments

Comments
 (0)