Skip to content

Getting Started

Jump to bottom
Brian Smith edited this page Jan 21, 2020 · 27 revisions

This document details the steps necessary to install SigkSens onto your ESP8266/ESP8285/ESP32 board (referred to from now on as "the MCU", for Micro-Controller Unit) and have it send data from one or more sensors to your SignalK Node Server. If you want only an overview of SigkSens, click here. If you've been through this document already, and are now ready to add an actual sensor, click here.

Prerequisites

  • You have the latest version of the Arduino IDE, or PlatformIO, installed and working. SigkSens currently works with either of these IDE's - you need only one of them.
  • You have one of the fully supported MCU's listed below.
  • You have successfully installed and run at least one program on the supported MCU. Even the most basic "Blink" program is fine, as this proves that your IDE is set up correctly and your computer and the MCU can communicate with each other. If you're using the Arduino IDE, Wemos has instructions for getting the Wemos D1 mini / mini Lite to work in the Arduino IDE, here.
  • You have successfully installed the SignalK Node Server (probably on a Raspberry Pi), and it's currently running. If you can bring up the SignalK Dashboard, it's installed and running. Click here for instructions for installing SignalK Node Server on a Raspberry Pi.

Supported MCU's

For now, the only fully supported MCU's are the Wemos D1 mini and Wemos D1 mini Lite. Various ESP32 boards have been tested as of year-end 2018, but not fully (the program compiles, but not many of the sensors have been tested yet, so proceed with an ESP32 with that caveat).

If you want to try the following installation on a different ESP8266/ESP8285 (1) board, or any ESP32 board, please do. (2) But first, make sure the pin assignments on it are the same as on the supported boards, or change them in ../SigkSens/config.h. There are several pins and related settings you need to make in that file - read it carefully to be sure you get them all.

(1) According to this article, the ESP8285 is an ESP8266 with flash memory onboard, so it should work, too.

(2) The board must have at least 1 meg of RAM, and if you connect more than 1 sensor to it, you may need more than that.

Installation Using Arduino IDE

(If you're using PlatformIO, skip to here)

  1. Plug the board into your computer with the USB-serial cable, then start the Arduino IDE.
  • a. Make sure you've selected the correct board: Tools - Board: Wemos D1 R2 & mini, or Wemos D1 mini Lite. If you're using an ESP32 board, you must first add the following URL to the "Additional Boards Manager URLs" field in File _ Preferences: https://dl.espressif.com/dl/package_esp32_dev_index.json - notice that this is the "dev" version of this URL!
  • b. Make sure the "Flash size" (Tools - Flash Size) includes some amount for SPIFFS. SPIFFS is the file system, where some of the configuration is stored. You probably won't have a choice smaller than 32K or even 64K - choose the smallest one offered, as long as it's at least 8K. (ESP32 boards present their memory configuration options differently - your best bet is to use the default configuration initially.)

  1. Go to File - Preferences and see what your "Sketchbook location" is. Mine is /home/butch/Documents/Arduino/mySketches, so I'll use that for the examples in the rest of the instructions. Yours will obviously be different.

  2. Log into the SigkSens repository on GitHub. (These instructions will tell you how to Download, but if you know how to use the "clone" feature, that's OK, too. As long as you end up with the same files in the correctly named folders when you're done.) Click the [Clone or Download] button, then Click "Download ZIP", and when prompted, select your Sketchbook folder. (In my example, /home/butch/Documents/Arduino/mySketches.) When the file has been downloaded, extract / unzip it to the same folder you downloaded it to. (If you have an option to "Extract to here", choose that.)

  3. A folder called SigkSens-master should be created in your Sketchbook folder, and all of the files in the project will be extracted inside it, including files in three sub-folders: hardware, Libraries, and SigkSens. You should also see several individual files.

  4. Rename the folder SigkSens-master to SigkSens. The Arduino IDE requires that the name of the sketch file (SigkSens.ino) and the name of the folder it's in be the same (without the .ino extension, of course). Be sure to match the case and spelling exactly.

  5. Exit the Arduino IDE, then restart it, and open the //SigkSens/SigkSens/SigkSens.ino file. The file should open, and you should NOT be prompted to create a folder named SigkSens - if you are, you did something wrong in Step 3, 4, or 5. Fix whatever you did wrong so that you have a SigkSens folder under your Sketch folder, and it has everything in it described in step 4. NOTE: there are two SigkSens folders, one under the other.

Install Libraries

If you're new to the Arduino IDE, you may not know about libraries yet. A library is a collection of code that does something complicated in a much simpler way, and SigkSens uses a number of them. There are several ways to install a library from the IDE, but we'll use only the two easiest ways below.

  1. Install the ReactESP library (steps 2 - 5). You'll find it here on GitHub.

  2. Click the [Clone or download] button, then click "Download ZIP". When prompted for the location to save it, select wherever you keep your Arduino-related files, or wherever you normally download files - this location isn't critical. A file called ReactESP-master.zip will be downloaded there. You can close the GitHub page now.

NOTE: If you have any trouble locating, or downloading the ZIP file for, any library that's used in SigkSens, you'll find the ZIP file for most of them in the ../SigkSens/Libraries folder.

  1. Open the SigkSens sketch file in the Arduino IDE (it may still be open from a few steps ago - if so, that's OK).

  2. From the main menu, select Sketch - Include library - Add .ZIP Library. Browse to wherever you saved ReactESP-master.zip in step 2, click on it, then click on [OK]. install zip library

  3. The ZIP file will be extracted to the folder where the Arduino IDE wants all of its library files, and you'll see "Library added to your libraries. Check 'include library' menu." in the middle of the IDE screen. (You don't need to check anything, though.) after adding a library in ide

  4. Install the following libraries using the "download and install from a ZIP file" method you just did in steps 2 - 5.

  • ESPAsyncTCP - here on GitHub.
  • ESPAsyncWebServer - here on GitHub.
  • AsyncTCP - here on GitHub.
  • WifiManager (dev version) - here on GitHub.
  • uSSDP (the version that's correct for your board): for ESP8266, or for ESP32. ONE OR THE OTHER - NOT BOTH! UPDATE: since this wiki page was written, a new version of uSSDP for the ESP8266 has a breaking change for SigkSens. The version that works can be found here. Copy it to your /libraries folder and unzip it - it should create a uSSDP-master-for-SigkSens folder with the correct files in it.
  • If you're using an ESP32, and you're using a OneWire temperature sensor, but you're NOT using a MAX31850 (a board for getting temperatures from a thermocouple through the OneWire interface), install this version of the OneWire library:. (If you're not using an ESP32, or you're using one and you're using a MAX31850 - see instructions below.)

  1. Install the ArduinoJson library. This time, it's going to be even easier, because ArduinoJson is one of the libraries included in the Arduino Library Manager. In the Arduino IDE, select Sketch - Include Library - Manage Libraries. After a few seconds, a very long list of Arduino libraries will appear. In the "Filter your search" field (upper right corner), type arduinojson, and click on the one called "ArduinoJson", authored by Benoit Blanchon. The latest version will be selected automatically, so click the [Install] button. The library will be installed, and the word "INSTALLED" will appear beside the name of the library. Leave Library Manager open - you're going to use it several more times.

  2. Install all of the following libraries using Library Manager. In each case, if there is a "Version" selection to be made, select the most recent one that's NOT a "beta" version.

  • WebSockets (by Marcus Sattler)
  • Adafruit ADS1X15 library (by Adafruit)
  • Adafruit Unified Sensor library (by Adafruit) (There are a LOT of Adafruit sensor libraries - this one is the one that's called exactly "Adafruit Unified Sensor".)
  • Adafruit BMP280 library (by Adafruit)
  • MAX31850 DallasTemp library (by Adafruit)
  • If you're using an ESP8266, install the MAX31850 OneWire library (by Adafruit)
  • If you're using an ESP32, and you ARE going to use a MAX31850, install the MAX31850 OneWire library (by Adafruit), but see Issue https://github.com/mxtommy/SigkSens/issues/67 - it will tell you how to get SigkSens to compile with that library. (Actually using a MAX31850 sensor hasn't been tested with it yet, though!)

  1. Close the Library Manager.

  2. Everything should now be ready to compile, so in the IDE, click the "Verify" button (the checkmark in a circle), or select Sketch - Verify/Compile from the main menu. It will likely take a minute or more to compile, especially the first time, so be patient, and watch the progress gauge. When it's finished, it will display "Done compiling", with some details about memory and variables. If you don't see "Done compiling" (see screenshot), something's wrong, and you can't continue, so you'll have to sort that out first.

If you get an error about LED_BUILTIN, it's probably because you're using an ESP32 board that doesn't define LED_BUILTIN. See Pull Request https://github.com/mxtommy/SigkSens/pull/69 and make the minor changes to your config.h and configReset.cpp.

  1. Click the "Upload" button (the right arrow in a circle), or select Sketch - Upload from the main menu. The compiled sketch should be copied to the board. When you see "Upload completed", you know it worked. Leave the MCU plugged into your computer - you're going to try to connect to it next.

  2. Hold in the Reset button on your MCU for at least three seconds, then release it. After a few seconds, when the reset is complete, you should see that the built-in LED on the MCU is off.

  3. Skip to Configure Network Settings

Installation Using PlatformIO

(Skip this section if you use the Arduino IDE)

TODO: write the instructions for PIO

Configure Network Settings

  1. Bring up a list of available wifi networks on your computer, phone, or tablet. One of them should be "Unconfigured Sensor" - select it. It's an open connection (no password), so it should connnect.

  2. A new browser tab or window may open automatically, or you may need to open one manually, then go to http://192.168.4.1. You'll see four choices: initial config screen

  • Configure WiFi (this scans for available networks)
  • Configure WiFi (No Scan) (this one doesn't, but it has an option to do so if you need to)
  • Info (shows a bunch of technical details about your device and your network)
  • Reset (resets your wifi configuration, which you would need to do if you incorrectly save the SSID or password of your network)

  1. Select either [Configure WiFi] (which will scan for available networks), or [Configure WiFi (No Scan)] (if you know the SSID of the network you want to connect to).

  2. On the next screen, select or enter the SSID of the network, and enter the password. Enter the name you want to give your MCU in the "hostname" field - no more than 16 characters, all letters and/or numbers. If you will have more than one MCU on your boat running SigkSens, be sure to use a descriptive name for each, like PortEngine, AftBilge, etc.

wifi config ready to save

  1. Click "Save". The info will be saved to the memory on the MCU, and the MCU will be restarted, and attempt to login to your network with the new information.

  2. The built-in LED will tell you if you did that right:

  • No LED at all: you did something wrong - probably entered the SSID or password incorrectly. Since the MCU can't connect to a network, it will restart and enter Access Point mode, and you can start again at step 1 above. (Some ESP32 boards don't have a built-in LED, in which case none of the LED flashing will work.)
  • Slow flashing LED (once every 2 seconds): you're connected to the network, but not your SignalK Node Server. Make sure the Node Server is running (try to bring up the SignalK Dashboard). If it is, it could be a configuration issue that will be revealed below.
  • Rapidly flashing LED (2 1/2 flashes per second): you're connected to the network, and to the SignalK Node Server, but no data is flowing from the MCU. This is likely because you haven't enabled any sensors in config.h. The "Local" sensor is enabled by default - did you disable it?
  • Irregularly flashing LED (like a dash-dash-dot in Morse Code): you're connected to the network and the Server, and data is flowing from the MCU. (Not necessarily all the way to the Server, though.)

First Test

You're ready to see if everything is working!

  1. In your IDE, bring up the Serial Monitor. You'll probably see a whole bunch of data scrolling by really fast - that's good! But it's not enough to know that SigkSens is properly communicating with the SignalK Node Server.

  2. Push and hold the "Reset" button on your MCU, and while it's held down, uncheck "Autoscroll" at the bottom of the Serial Monitor, and click the [Clear output] button. Now release the "Reset" button and the MCU will restart. (TODO: add PIO instructions for allowing you to see just the first lines of the output easily.)

  3. The Serial Monitor output should look something like the screenshot below. (It's from the Arduino IDE - the PlatformIO output will look different, but the output should be the same.) sigksens serial monitor after successful connection

Near the top, there are several lines that begin with "#WM". One of them is the IP address that's been assigned to your MCU. Write it down - you'll need it below and at various times in the future.

In the serial monitor, scroll down below the data that's visible in the screenshot, and you'll see some lines that look like this:

mDNS responder started at WemosD1Lite
Starting SSDP...
starting webserver
Found server with IP/Port: 192.168.10.58:3000
Websocket client starting!
Ready!
[WSc] Connected to url: /signalk/v1/stream

This tells you that your SignalK Node Server:

  • is at 192.168.10.58 (the IP address of your Raspberry Pi, probably)
  • is using Port 3000
  • is at /signalk/v1/stream on the server

More important, it tells you that SigkSens was able to find and connect to SignalK! But SignalK won't accept data from SigkSens until it passes in a Security Token, which it doesn't yet have.

  1. You need to request a security token from the Signalk Node Server, and then tell SigkSens what that token is. From a command line on the computer running your SignalK, enter:

    signalk-generate-token -u yourSignalKusername -e "99y" -s ./.signalk/security.json

If you did a standard installation of SignalK, the above command line should work, as soon as you change yourSignalKusername to whatever your SignalK username actually is. The result will be a really, really long text string made of all kinds of characters. That's your "token". "99y" is for "99 years" - so you don't have to worry about it again.

  1. Now that you have the token, you need to tell SigkSens what it is. Do this from your browser (replace 1.2.3.4 with your MCU's IP address, which you should have written down earlier):

    http://1.2.3.4/setSignalKToken?token=<your token here, not in brackets or quotes or anything>

example: http://10.10.0.108/setSignalKToken?token=3kdieltjiele99trl30kkll (your actual token will be much longer)

Your MCU should restart (if not, do it manually), and you should see the new token in the Serial Monitor output, shortly after the lines that begin with *WM.

  1. Back to the Serial Monitor output: the entire "sensors" section should look just like it does in the screenshot above, except for the three "value" numbers. Those are from the "Local" sensor, which isn't a sensor at all. Rather, it's data from your MCU (the clock speed of the processor, the amount of free memory at the moment, and the number of seconds since the last reset), formatted like it's data from an actual sensor. It's always there, and always on, so you always have some data flowing for testing purpsoses. (If you really don't want it, comment out the #define ENABLE_SYSTEMHZ line in config.h.)

Everything after that is data, from the "Local" sensor, flowing to your SignalK Node Server. It submits data once per second, so if you scroll down in the Serial Monitor, you should see a LOT of data.

If everything looks OK in the Serial Monitor, the only thing left is to see if the data is making it to the SignalK Node Server. So open the SignalK Dashboard, and you should see, in the "Provider activity (deltas/second)" section, something like the screenshot below . The "ws" means this data is coming from a WebSocket connection (that's how SigkSens connects to the SignalK Node Server), and "butch" is the SignalK username through which SigkSens is logged in. The 0.8 is the number of new data submissions that are happening per second, and the 3 (under "Number of Signal K Paths") is the number of sensors that are currently reporting data (systemHz, freeMem, and uptime, from the "Local" sensor). sk dashboard

Congratulations! Your MCU is sending data to your SignalK Node Server, and the Node Server is displaying it! That's pretty much everything you could want SigkSens to do for you, isn't it? Well, except for reporting actual data from actual sensors. And that's covered in the Add A Sensor document.

If you want to see your data in a real SignalK app, go to the Webapps menu item in the Dashboard, then select the Instrument Panel. Somewhere in it, you should find the output of your "Local" sensor:

output in instrument panel

One last thing. Here's a quick way to see what your MCU is doing at any time (what data it's sending, or at least trying to send, to the SignalK Node Server). In a browser, simply type the IP address of your MCU and hit . It will display something like this:

last delta page

Configure the MCU with the API

If you've gotten this far and everything is working, you can skip the rest of this document and go right to the Add A Sensor document. But if any of the settings aren't correct in the Serial Monitor output, you'll have to do one or more of these things. No worries: it's simple, and should have to be done only once for each MCU, unless you make changes to your setup that aren't detected automatically.

In each case, you run a url in a browser, from a phone / tablet / computer connected to the same network that you MCU is connected to. In the examples below, you must replace "1.2.3.4" with the IP address of your MCU. (It's displayed in the first several lines of output in the Serial Monitor whenever SigkSens starts, and you should have written it down earlier, and held onto it.)

/setNewHostname

Set your MCU's hostname. Replace "myMCUname" with the name you want for your MCU. Limited to 16 characters, numbers and letters only. (This would have been set in your initial configuration, but maybe you want to change it.)

example: http://1.2.3.4/setNewHostname?hostname=myMCUname

/setSignalKHost

Set the IP address of the computer that your SignalK Node Server is running on (your SignalK Host). Replace "10.10.0.100" with yours. Necessary only if mDNS isn't working properly.

example: http://1.2.3.4/setSignalKHost?host=10.10.0.100

/setSignalKPort

Set the HTTP Port that your SignalK Node Server is listening on. The default for SigkSens is 80, but the default for the SignalK Node Server is 3000, and yours could be either, or something else. Necessary only if mDNS isn't working properly. NOTE: As of this writing (December, 2018), SigkSens doesn't support SSL. If you experience connection problems make sure that the port you have configured supports non-SSL connections. Enabling SSL on the Node Server will make all WebSocket connections use SSL and SigkSens will not work.

example: http://1.2.3.4/setSignalKPort?port=3000

/setSignalKPath

Set the url of your SignalK Node Server, at your SignalK Host. Default is /signalk/v1/stream, and it really shouldn't be anything else, but it's possible. Necessary only if mDNS isn't working properly.

example: http://1.2.3.4/setSignalKPath?path=/signalk/v1/stream

Reset Wifi Configuration

For any number of reasons, you may want to reset the wifi configuration of your MCU. The most likely reason is that you've changed the SSID or password of the wifi network you want it to connect to. From any phone / tablet / computer connected to the same network as your MCU, run this in a browser:

http://1.2.3.4/resetConfig

This will erase the SSID and password of the network you have been connecting to, as well as the hostname of your MCU. If you use the hostname in any other program, be sure to write down the name before you do the reset, so you can re-enter it exactly the same as before. It will also restart the MCU in AP (access point) mode, with the network named "Unconfigured Sensor". See "Configure Network Settings" for what to do next.

Clone this wiki locally