ser2bt-bridge

Serial to Bluetooth bridge for raspberry pi zero w & w2:

Definitions:

I tend to use several different descriptors for each component that is involved with this project, so I've tried to define them below:

For the purpose of this project, the terms slave refers to a end device you want to connect to, such as a router, switch, Firewall, Wireless LAN Controller, or any appliance that has a console interface.
The terms master refers to the PC, laptop, phone, or tablet that is being usede to connect to the slave device.
The terms bridge, or pi refer to the raspberry pi zero w/w2, that is being used to bridge the master to slave device.
The terms user, you, network engineer, network administrator, administrator, or engineer all refer to the person using this bridge.

Preamble:

This project is made up of a set of scripts, services and libraries (used loosely) that allow a user to connect "through" a raspberry pi zero w from their phone/tablet/laptop's bluetooth interface to the console port on a slave device such as a switch, router, firewall, etc. This allows the user to manage slave devices via it's console port, while enjoying the benefit of not having to be tethered right up to it.

How it works at a high level/Feature List:

These scripts and services basicaly utilize screen and rfcomm to "bridge" a connection between the master, and the slave device you are attempting to connect to.

By design, this prject does not have security in mind, preferring instead to focus on easy discovery, pairing, and connectivity to allow the network administrator to focus on getting their work done.
- The Bridge will always be discoverable, and will not require a pin to complete the pairing process.
- ser2bt-bridge has been tested with master devices using the following Operating Systems: Linux, Android, Windows 10, and ChromeOS (with caveats).
  - Although I do not own a mac, I have no reason to belive it won't work with ser2bt-bridge.
- When connecting to the bridge over bluetooth, the administrator will be auto logged-in to it as user pi.
  - This will in no way affect access to the slave device. If the slave requires a username/password to administer it, then you will still be required to use those credentials.
Once the master is connected to the bridge, it will attempt to look for any available serial (usb or acm) ports. At this point 1 of 3 things are expected to occur:
1. If the bridge was connected to a single slave, then it will open a screen session to that serial port outomagically.
2. If the bridge was connected (via OTG usb hub) to multiple switches, then it will create one screen session for each active serial port found, list them on your display, and exit to shell.
  - There will be instructions on the monitor telling you how to access each screen.
3. If the bridge does not detect any new usb/acm ports, then the it will state that fact and then drop the user to the bash shell.
  - If you connect the bridge to the slave after power on, and initial detection of the usb/acm ports, then type the following command to have it look for connected ports: ser2bt-bridge
The connection between the bidge and the slave is set to 9600 Baud. I'm looking to set this as a configurable element in the future. But as the baud rate goes up, the range one can walk away from the bridge will go down.
While connected to a slave, the bridge will begin logging all session traffic between the master and slave. (This is why it is important to make sure the bridge somehow either has its time set manually, or receives its time from an external source, such as ntp server and/or an onboard rtc.)
If you become disconnected from the bridge, and want to reconnect, do not try to use the terminal program's reconnect feature. In order to reconnect, first close the window, then re-open the connection profile.
If your setup has one of the two UPS's listed below, then services that will monitor battery level, and will automatically shutdown if the battery level reaches 2%.
- If you are using the PiSugar2 UPS, then you get several added benefits:
  - An on board RTC.
  - A button to safely turn off the bridge when you are done using it. This makes it so much easier then having to login just to power it off:
  - Short-press - between 1 to 2 seconds will cause the bridge to safely shutdown.
  - Long-press - between 3 - 4 seconds will cause the bridge to safely reboot.
If your setup has a waveshare e-ink screen, then there are services that will continiously upate the state of the bridge on the display.
Telnet is installed and is used for bridging to serial connections via ser2net. This is just to provide another method to connect to a slave device.
If your bridge does not have a connected UPS solution, and you are relying on the slave's USB port to supply power to your bridge, and decide to reboot the slave, your bridge will most likely be un-gracefully powercycled along with it. This is not good as there is a risk that your Pi's SD card will become corrupted.

Setup:

There are two different setup options, basic, and full:

Basic should be used if you are only using a pi, and do not wish (at this point) to add a screen, or an external battery.
Full should be used if you are using the pi, either the e-ink display and/or an external UPS. By selecting full the upgrade script will determine what is hardware is attatched, and install the necessary software to make it work.

Basic setup:

The following steps will guide you through the process getting this system to work from just after everything is unboxed, to the point where you are connecting to a switch, router, or whatever - that is the raspberry pi zero, by itself acting as a bluetooth to serial bridge. We will be using headless installation method, so you will not need a keyboard, mouse, or monitor.

Parts needed for Basic setup:

A raspberry pi zero w - at a minimum, but if you don't like soldering, and have at least a desire to expand, get the raspberry pi zero wh instead.
An SD card with a minimum size of 8G. You'll need to get a quality card to weather accidental power-cuts. A good example is: Example
A USB type A to RJ45 serial cable: Example
A USB micro to USB type A for power: Example
A USB micro to USB type A Female to connect to a USB type A to RJ45 serial cable to connect to a Cisco RJ45 console port: Example.
A Micro USB (Pi side) to Mini USB (switch side) to connect between the raspberry pi's usb port to the switches USB-console port: Example
Optional: A Micro USB (pi side) to USB A female OTG Hub. This will permit you to connect the bridge to multiple slave devices, so you won't have to keep walking back to switch the cable back and forth. A good example is if you have VSS/Stack, or a FHRP pair: Example
A case to house the pi. Check this option out for a good example, slightly pricey, but in my opinion, worth the cost. Down side is that it will not work with the raspberry pi wh's.

Full setup:

Additional parts needed for Full setup:

For UPS, there are two supported options:
- The first option is a ups-lite.
- The second UPS option is a PiSugar2 which includes a built-in real time clock (RTC), and a button that can be controlled via software.
  - The bridge will take advantage both the rtc, and button.
For status and system health updates, attach a waveshare.2.13 e-paper display. Make sure it says V2, for Version 2.
Attatch the e-paper display and UPS per the manufacturers instructions.

Installation:

OS installation and setup:

insert the SD card into a different computer to perform the first few steps:
- Download link is for the imager here.
- Now open the imager and perform the following steps:
  - Select the Raspberry Pi OS (Other) option.
  - Then select the Raspberry Pi OS lite option.
  - Then select the Choose Storage button, and select your SD card.
  - Next, select the advanced (gears) button. and fill in:
    - hostname
    - Check SSH, and make sure use password authentication is selected.
    - Set username and password.
    - Check Configure Wireless LAN.
      - Put in your wireless LAN credentials (SSID & WPA passphrase).
      - Select the Country you are in.
    - Check Locale settings:
      - Set timezone and keyboard layout.
  - Click on Save.
  - Click on Write.

You are now done with this section, safely eject the SD card, and insert it into you raspberry pi zero.

First login:

Power on the bridge, and give it about a minute to boot.
- Using your favorite SSH client, login into your pi: pi@<[hostname|IP Address]>, where hostname, or IP Address is = to your Pi's.

Update OS:

sudo apt update && sudo apt full-upgrade -y

Reboot your Pi when the upgrade is complete.

Additional OS Setup:

Install git:

sudo apt install git -y

Setup using raspi-config

Enter sudo raspi-config:
From the main menu, under Advanced Options.
- select Expand Filesystem to expand.
From the main menu, under System Options.
- Select Boot / Autologin, then select Console Autologin.
- Select Network at boot, then select No to Disable Waiting for network on boot.
From the Main Menu, select Finish, and even if you are not asked to reboot, do so.

Additional Network Setup:

In order for your bridge to keep the correct time, perform updates, or allow an alternate way to access the it, it is advisable you add more wireless networks into your wpa_supplicant.conf. Examples include: allowable work networks, your home network, your hotspot, and even hotspots of your peer's phones (as allowed).

Open /etc/wpa_supplicant/wpa_supplicant.conf, and add the following:

network={
    ssid="<SSID>"
    psk="<passphrase/password>"
    key_mgmt=WPA-PSK
}

One block for each network you want to add.
- Make sure to set the ssid and psk as needed.
- Be sure to test each network.

Pre-Requisites to software installation:

mkdir -p /home/pi/Projects/

Download and setup the serial to bluetooth scripts:

In the Projects folder, initialize git, and clone the following repository:

cd $HOME/Projects/
git init
git clone https://github.com/lgbrownjr/ser2bt-bridge.git

Run the upgrade tool:

cd ser2bt-bridge/
sudo ./upgrade [basic|full]

We're Done!

If everything went as planned, your raspberry pi zero w should be acting like a bluetooth to serial bridge, allowing you to connect to a switche's console port via bluetooth from your computer.

Now, reboot your bridge and skip down to How to use:

How to use:

Power on the bridge:

Different ways, depending on your setup:
1. For the basic bridge option, Plug the power into it's power port. See the diagram here:
2. If your version of the bridge has a UPS, then slide the switch to the on position. a. If your UPS is a PiShugar2: 1. The real time clock should be enabeled and providing your pi with the correct time, while it is off of the internet. b. To charge the UPS, insert the power cord into the UPS's power input plug, and not the the pi's power port.
It will take up to 45 seconds to boot to a point where a you can connect to it via bluetooth.

NOTE

If you are interested in accurate time and you are using a pi without a UPS connected, I advise you connect it to an available hotspot, or wlan within range. See: Additional Network Setup

First time connecting to your bridge:

Pairing:

The Bridge is set to allways be available to pair with it, so this step should go by fairly easily and painlessly:
1. Open bluetooth settings and pair with the bridge - the name of the bridge should be the hostname you assigned it during the setup. See Additional OS Setup:.
2. Assign com/tty ports to the bridge device. Pairing should now be complete!

Setting up your Favourite Terminal application to connect to your Bridge:

In your favourite terminal program (screen/minicom/putty/securecrt/etc).
Create a connection profile to connect to your bridge using serial, and assign the profile the com/tty port that was assigned during pairing.
Use N81, and 9600 baud.
Use xterm as your terminal type.
Now save and test.
Repeat steps for all devices that you might think that will need to connect. You should now all of your device terminal programs setup to easily connect to the bridge as needed.

Connecting to your bridge:

Open your terminal program.
Click on and launch/open the connection profile you just built.
A terminal should open up, and you should see the banner appear, along with the results of your bridges attemtps to connect to the slave(s), and then either the login prompt of the slave, or a list of possible slaves you can conncect with.

Shutdown/Reboot your bridge:

To shutdown your bridge, type sudo poweroff
To reboot your bridge, type sudo reboot
If you have a PiSugar2 UPS:
- Short press the button (between 1 - 2 seconds) to power it down.
- Long press the power button for 3 - 4 seconds, to reboot.
If you are connected to any one of the UPS options, slide the switch to the off position once the shutdown process is complete.

How To:

If you were dropped off in the bridge's bash shell, you have access to perform updates, play games, set the time, whatever. Here are some ideas:
1. Set the timezone (for those travelers)
  - follow from here: Setup Using raspi-config
2. Set the date and time (if you don't have an onboard rtc, or access to a network:
  - `sudo date --set="4 MAR 2021 18:00:00"
3. Update the ser2bt software - if you are connected using bluetooth, then start at step 1, otherwise, skip step 1 and step 5:
  - screen
  - cd /home/pi/Projects/ser2bt/
  - git pull
  - sudo ./upgrade [basic|full]
  - exit to exit out of acreen.
4. Update the OS: (this is also done in the upgrade utility.)
  - screen Need to use screen to be able to access network resources, this is a workaround to an issue that prevents reliable network communications while an admin is logged in.
  - sudo apt update -y
5. If the result of the above command included no updates available, then skip to step 4.
  - sudo apt full-upgrade -y
  - exit to exit out of screen.
If your bridge is connected to a single slave:
1. ctrl + a, then d to suspend you screen session.
2. ctrl + a, then \ to terminate your screen session. (you can always re-enter).
3. If you want to enter a serial session, and you either terminated the session prior, or plugged a cable in after boot, then run ser2bt_bridge.
4. To return to an existing session after it has been suspended, then type screen -r
If your bridge is connected to multiple slaves:
1. If you are in the slave (read switch), and you want to get out to do something or enter another switch, and come back, then:
2. ctrl + a, then d to suspend you screen session allowing you to return later.
3. ctrl + a, then \ to terminate your screen session. (you can always re-enter).
4. To re-nter a session that has been suspended, type screen -r Switch_x.
5. To enter a switch that has never been entered, or had its screen session terminated, type screen Switch_x where x = the connection number.
6. To list the available switches that you can enter, type screen -l
If you're lost, and you need to reconnect to the slave were connected to, type ser2bt_bridge to relaunch the discovery script. if that gives you an error, then reboot.
To resize your terminal, suspend/exit and screen sessions, and type resize
When you are within a screen session, configuring, or administering a slave:
1. Use the PageUp key to enter scrolback mode, then continue to use PageUp/PageDown or Up/Down arrows to move up and down your buffer. Use the Escape key to exit, and go back to the normal mode.

Improvements:

Features I want to add to this project:

Add a session logging feature for sessions that are connected to a switch, or router.
Build an installation script to automate most of the installation steps.
add support for RTC (Real Time Clocks) so as not to have to rely on ntp so much, especially in envornments where there is no wifi available to the pi.
upgrade utility now installs everything wether you have a basic setup, or the full setup.
Add support for USB micro to OTG HUB's to allow connectivity to more than one slave at a time.
I'm not sure if this even doable, but attempt to allow multiple concurrent bluetooth connections, especially if the item listed above is completed.
Continue testing Overlay FS as a means to protect the SD cards from corruption.

Known issues:

For some reason, while connected via bluetooth, one cannot update the OS, or githib repositories. A workaround, is to open a screen session in the bridge, then perform any update taskes. Another workaround would be to ssh into it instead of using bluetooth.

lgbrownjr / ser2bt-bridge Goto Github PK

ser2bt-bridge's Introduction