mirror/SimplySerial
1
0
Fork 0
mirror of https://github.com/fasteddy516/SimplySerial.git synced 2024-11-24 10:04:35 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
fasteddy516 2019-06-10 14:19:23 -04:00 committed by GitHub
parent 71adc56396
commit 3dd1f7db8f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 26 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
README.md
View File

@ -2,33 +2,45 @@
###### A serial terminal that runs as a Windows console application.
Written by [Edward Wright](mailto:fasteddy@thewrightspace.net) (fasteddy516).
Written by [Edward Wright](mailto:fasteddy@thewrightspace.net) (fasteddy516).
Available at https://github.com/fasteddy516/SimplySerial
_SimplySerial is written in C# and requires that .NET Framework 4.6.1 or newer is installed. There is a pretty good chance it is already installed on any modern Windows operating system, but if not, it can be downloaded from Microsoft at https://dotnet.microsoft.com/download/dotnet-framework._
Available at https://github.com/fasteddy516/SimplySerial
# Description
SimplySerial is a basic serial terminal that runs as a Windows console application. It provides a quick way to connect to - and communicate with - serial devices through the Windows Command Prompt or PowerShell.
SimplySerial is a basic serial terminal that runs as a Windows console application. It provides a quick way to connect to - and communicate with - serial devices through the Windows Command Prompt or PowerShell. SimplySerial can be used directly from Command Prompt/PowerShell and should work with most devices that appear in Device Manager as "COMx". It was, however, written specifically for
use within a "terminal" window in [Visual Studio Code](https://code.visualstudio.com/https://code.visualstudio.com/) to provide serial communications with devices running [CircuitPython](https://circuitpython.org/). Most of the testing and development of this application was done with this use case in mind.
SimplySerial can be used directly from Command Prompt/PowerShell and should work with most
devices that appear in Device Manager as "COMxx". It was, however, written specifically for
use within a "terminal" window in [Visual Studio Code](https://code.visualstudio.com/https://code.visualstudio.com/) to provide serial communications with devices running CircuitPython. Most of the testing and development of this application was done with this use case in mind.
# Requirements
* Windows 7, 8, 8.1 or 10
* .NET Framework 4.5 or newer
_The required version of .NET framework is already included in Windows 8 and newer. If you're running Windows 7, you may need to download and install it from Microsoft at https://dotnet.microsoft.com/download/dotnet-framework._
# Installation
* If it is not already installed, download and install the [.NET Framework 4.6.1 Runtime](https://dotnet.microsoft.com/download/dotnet-framework/net461).
* Download the [latest release](https://github.com/fasteddy516/SimplySerial/releases/latest) of this application.
* Open the `.zip` archive that you downloaded and move the `ss.exe` file to a location of your choosing.
* For easy access from the command prompt (if you want to be able to type `ss` from any directory/folder and have it open a serial terminal), you need to add the folder into which you placed `ss.exe` to your `PATH`. _(For more information on adding folders to the `PATH`, see [this HowToGeek article](https://www.howtogeek.com/118594/how-to-edit-your-system-path-for-easy-command-line-access/))._
Download the [latest release](https://github.com/fasteddy516/SimplySerial/releases/latest) of this application in one of two formats:
`SimplySerial_x.x.x_setup.msi` is a windows installer package that puts everything where it needs to go and adds the location of the SimplySerial executable to your `PATH` environment variable, which makes it easily accessible from Command Prompt, PowerShell and Visual Studio Code. **This is the preferred installation method.**
`SimplySerial_x.x.x_standalone.zip` is a standard compressed archive containing the SimplySerial executable and some documentation. You can unzip it whereever you like, and add that location to your `PATH` or not. **Advanced users may prefer this format/process.**
# Using SimplySerial
By default, SimplySerial will attempt to identify and connect to a CircuitPython-capable board at 9600 baud, no parity, 8 data bits and 1 stop bit. If no known boards are detected, it will default to the first available serial (COM) port. If you added the `ss.exe` location to your `PATH`, only have one active CircuitPython board (or COM port) on your machine, and that board/port is a device running CircuitPython (or anything that uses those particular port settings), entering the `ss` command while in Command Prompt or PowerShell should be all you have to do to connect. If you have multiple COM ports, or need to use different communications settings, you will need to use the appropriate command-line arguments listed below.
For CircuitPython users, type `ss` in a Command Prompt, PowerShell or VSCode Terminal Window and press `enter`. That's it!
By default, SimplySerial will attempt to identify and connect to a CircuitPython-capable board at 9600 baud, no parity, 8 data bits and 1 stop bit. If no known boards are detected, it will default to the first available serial (COM) port. If there are no COM ports available, it will wait until one shows up, then connect to it.
Once you're connected, you should see messages from the device on COMx appear on screen, and anything you type into Command Prompt/PowerShell will be sent to the device. CircuitPython users can access the REPL using `CTRL-C` and exit the REPL using `CTRL-D`.
You can exit SimplySerial any time by pressing `CTRL-X`.
If you have multiple COM ports, multiple CircuitPython devices connected, or need to use different communications settings, you will need to use the appropriate command-line arguments listed below:
`-h, --help` displays a list of valid command-line arguments
@ -50,10 +62,6 @@
If you wanted to connect to a device on COM17 at 115200 baud, you would use the command `ss -c:17 -b:115200`, or if you really enjoy typing `ss --com:17 --baud:115200`.
Once you're connected, you should see messages from the device on COMxx appear on screen, and anything you type into Command Prompt/PowerShell will be sent to the device.
To disconnect and exit SimplySerial, press `CTRL-X` at any time.
# Auto-(re)connect functionality
@ -68,7 +76,7 @@ To disconnect and exit SimplySerial, press `CTRL-X` at any time.
# Using SimplySerial in Visual Studio Code (VSCode)
In a standard installation of VSCode, opening a "terminal" gets you a Command Prompt or PowerShell window embedded in the VSCode interface. SimplySerial works exactly the same within this embedded window as it does in a normal Command Prompt or PowerShell, which means if you fit the "easy use case scenario" mentioned above (`ss.exe` added to path, single COM port, 9600 baud, etc.), using SimplySerial within VSCode is as easy as opening a terminal window via the menu bar (`Terminal > New Terminal`) or shortcut key, typing `ss` and pressing enter.
In a standard installation of VSCode, opening a "terminal" gets you a Command Prompt or PowerShell window embedded in the VSCode interface. SimplySerial works exactly the same within this embedded window as it does in a normal Command Prompt or PowerShell, which means using SimplySerial within VSCode is as easy as opening a terminal window via the menu bar (`Terminal > New Terminal`) or shortcut key, typing `ss` and pressing enter.
If you want to make things even simpler, or if you need to use a bunch of command-line arguments and don't want to enter them every time (**and you don't use the terminal window in Visual Studio Code for anything else**) you can have VSCode launch SimplySerial directly whenever you open a terminal window by changing the `terminal.integrated.shell.windows` setting to point to `ss.exe` + any arguments you need to add. This works well, but will prevent you from having multiple VSCode terminal windows open, as only one application can connect to any given serial port at a given time.