Build a Fingerprint reader with Adafruit Feather HUZZAH w/ESP8266 and Medium One’s Prototyping Sandbox

This tutorial uses the Medium One IoT Prototyping Sandbox to control a fingerprint reader.

Prerequisite:

  • ESP8266 Quick Start Guide [Go-Here]

In this tutorial, you will:

  • Set up the Medium One IoT Controller app to send the Fingerprint scan commands to Medium One Workflows and receive messages from a Medium One Workflow.
  • Use a Medium One Workflow to relay the commands from the IoT Controller app to an ESP8266 processor that controls the fingerprint reader. The Medium One Workflows will receive the status of the operation upon completion.
  • Use the Workflows to communicate to users by displaying instructional messages like “Verify mode: Please place your finger on reader” or status messages like “The operation is successful” on the Medium One IoT Controller app’s message widget.

Here’s what you need to get started:

  • Medium One IoT Prototyping Sandbox [Buy Link]
  • Feather HUZZAH w/ESP8266 [Buy-3046]
  • CP2104 USB Driver [download]
  • Windows PC or Mac OS
    • Note, this tutorial is based on Window PC
  • 4 GHz WiFi Internet Access
  • Medium One IoT Controller App [download]
  • Arduino IDE [download]
  • Parallax Optical Sensor Development Tools Fingerprint Reader [Buy_Link]

 

STEP 1: SET UP Fingerprint reader and Adafruit ESP8266 Feather (schematic)

Note: The Parallax Fingerprint Reader Module is supplied by a +5V AC to DC adaptor (the connector jack in the upper left corner.)   This device works best at VCC=5.0V.  The placement of the finger on the scanner and the lighting of the surrounding can be critical factors in how well the scan works.

 

STEP 2: SET UP THE MOBILE APP

Note: These instructions are for the Android app, but the IOS app is similar.

Open the IoT Controller app and click on the plus sign in the bottom corner.

Now you can give your project a name and input your Username, Password, and API Key from the account set up. Select “Sandbox”. Then press “Done”.

If you entered everything correctly, you should see two blue circular icons on the bottom.  If you entered something incorrectly, the color of the of the plus circular icon will be red instead of blue.

Next, press “+Add New Widget”.

Select “Switch”.  Swipe the whole “switch” block to the right to access the settings.

The stream field is represented by a two-arrow icon.  The tag field is represented by a price tag icon. The delete button is represented by a trash can icon.

Press each icon to enter the field.  Type “raw” for the stream, and “redledsw” for the tag.

Press “+ Add New Widget” again.  Four more similar switches are created.   At the end, this is what your screen will look like.

Next, press “+Add New Widget”.

Select “Notification”.  Swipe the whole “Notification” block to the right to access the settings.

Press each icon to enter the field.  Type “notifications” for the stream, and “message” for the tag.

At the end, there are four “switch” blocks and one “notification” block.  The tag name will appear on each widget.

 

Checkpoint

Go to your Medium One account and go to the “Dashboard” from the left-hand sidebar.  Click “Single User Real Time Events Stream”.

Select your user in the right hand corner of the widget.

Now, on the app, click on the “redledsw” switch to turn it on.

You should see an event show up on the widget.

Click the save icon (floppy disk) in the top right corner of the dashboard.

 

STEP 3: SET UP THE ESP8266 BOARD

Go to Tools > Board > Boards Manager …

 

Search for “esp8266” and install the boards.

Go to Tools -> Board:”Adafruit HUZZAH ESP8266”

 

Download the firmware by clicking this link. https://github.com/Medium-One/esp8266_labs/tree/master/Parallax_Fingerprint_Scanner/Huzzah_ESP8266_Feather_arduino_c_code

Fill in your Sandbox and Wifi credentials where necessary near the top portion code.

For example, it will look something like this:

 

 

STEP 4: PROGRAMMING THE BOARD

Connect your board to your PC via USB.

 

 

Next, go to Tools -> Port.  Select the correct com port.

Then click on the upload arrow in the top left corner to compile and flash the board, this may take a few minutes.

Note the output log during this step to see when it’s completed.

Once complete, go back to your Medium One Dashboard, where the Real Time Events Stream should be open. You should eventually receive an event from your board within a minute.

You should go to Tools -> Serial Monitor to see print statements from the board, so that you can see when the board connects to the WiFi.

Set the baud rate to 115200.

You will also receive a heartbeat event from the board every minute.

Unplug your board.

 

STEP 5: WRITE WORKFLOW 1: SWITCH LED

Press these two switches to send event data to the sandbox.

The events will appear on the dashboard.

Go to “Config” on the left-hand sidebar in your Medium One account and click “Data Streams”.

Click “raw” and then click the active checkbox next to “redledsw” and “greenledsw”. Then click “Save Data Stream”.

Now go to your Workflow Studio in your Medium One account and click “Create”.

Give your workflow a name. We named ours “LED Control”.

Click the “Tags and Triggers” icon, which is the first icon on the right-hand sidebar.

Click “raw” and drag the “redledsw” and “greenledsw” tags into the main area of the workflow.

Now click on the “Modules” icon (the second icon in the sidebar), click on “Foundation” and drag a “Base Python” module into the workflow.

Double click on the base python block.  Click to add the 2nd input called in2.   Then press “save”.

Connect the bottom end of the switch tag to the “in1” and “in2” circles on the Base Python module.

Double-click on the Base Python module and copy and paste the following code into the Script section, replacing any code that is originally there.

Now click “Save and Activate”.

 

Checkpoint

Plug the board in and open the IoT Controller app.

The board will enter the initial setup (both green and yellow led’s are turned on.)   Wait for all the leds to be turned off.

After the board is done setting up (within a minute), turn the app switch on and off. You should see the LED on the board turn on and off.

Note: Blue Led is enabled by the greenledsw switch.

The events are displayed on the dashboard.

STEP 6: WRITE WORKFLOW 2: Set Fingerprint Processing Mode (Add, Delete, Verify)

This workflow waits to get the user’s selection of the fingerprint operation mode from the Medium One Mobile IoT app.   Upon receiving the user’s selected mode, the workflow sends a confirmation message back to the app that the mode is set.  The message also includes an instruction about what the user needs to do such as placing your finger on the scanner for the add or verify mode.   At the same time, the mode (add, delete, or verify) is sent to ESP8266.  ESP8266 will process the mode by sending the actual command to the fingerprint module.  The blue led is turned on to show that the operation is in progress and is turned off when the operation is done.

Below are the instructions to create this workflow.

Press these three switches to send event data to the sandbox.

The events will appear.

Go to “Config” from the left-hand sidebar on your Medium One account and click “Data Streams”.

Click “raw” and then click the active checkbox next to “add_user_mode” and “del_user_mode”, and “vfy_user_mode”. Then click “Save Data Stream”.

Create a new stream called notification.  Click on “Create New Stream”.

Enter “notifications” for the Name field.  Choose “Never Expire.” Click “Save Data Stream.”

The new data stream is created.

Create a new workflow, name it, and drag the raw “add_user_mode” and “del_user_mode”, and “vfy_user_mode” tags into the workflow.

Drag a Base Python module into the workflow.

Double click on the base python block.  Click to add the 2nd input called in2.  Click to add the 3rd input called in3.  Then press “save”.

Click the “Outputs” icon (third icon on sidebar) and drag one “Processed Stream – Single” output into the workflow.

Double click “Processed Stream – Single” output block.

Choose “notifications” for Datastreams field.   Click “Save.”

Connect the blocks as shown below.

Copy and paste the following code into the Script area, replacing any code that was previously there. Then click “Save”.

Now click on the “Revisions” icon (second from the bottom of the sidebar).

Click the checkmark under the latest revision to activate the workflow if it’s not activated.

 

STEP 7: WRITE WORKFLOW 3: Get the Operation Result Status on Your IoT app.

This workflow displays the message on the Medium One Mobile IoT App whether the operation is successful or unsuccessful.

First, create this new tag with the IoT app. Pick the JSON widget by clicking it.

Swipe the widget to the left for configuration setup.

Three icons will be shown.   The first two icons configure the stream and tag properties.

Click on the set stream icon and enter “raw”.  Click “SAVE.”

Click on the set tag icon and enter “operation_status”.  Click SAVE.

Enter “Pass” and press the POST button.

The data will appear on the dashboard.

Go to “Config” from the left-hand sidebar on your Medium One account and click “Data Streams”.

Click “raw” and then click the active checkbox next to “operation_status.” Then click “Save Data Stream”.

Create a new workflow, name it, and drag the raw “operation_status” tags into the workflow.

Drag a Base Python module into the workflow.

Click the “Outputs” icon (third icon on sidebar) and drag one “Processed Stream – Single” output into the workflow.

Double click “Processed Stream – Single” output block. Choose “notifications” for Datastreams field.   Click “Save.”

Connect the blocks as shown below.

Copy and paste the following code into the Script area, replacing any code that was previously there. Then click “Save and Activate”.

Now this widget can be removed since creating the workflow is done.

Swipe the widget to the left for configuration setup.  Three icons will be shown.  Click the trash can to remove the widget.

Checkpoint

Go to your Mobile App.

Add a new user’s fingerprint:

Click the “add_user_mode” switch to change the state from OFF to ON.  A message will appear to indicate that the scanner is ready to scan your fingerprint.  When the blue LED on ESP8266 board is turned on, place your fingerprint on the scanner.  Keep your fingerprint until the blue LED is disabled.

Adding a new user’s fingerprint is a long process that may take a few minutes.

If the operation is successful, a message below will be displayed.

If the operation is unsuccessful, a different message will be displayed.  The red led is turned on.

Click the “add_user_mode” switch to change the state from ON to OFF.  A message will appear to indicate that it is back to idle mode.

If the serial monitor is open, it shows that the fingerprint is making three scans for adding a new user’s fingerprint.  If all three scans succeed, then the firmware will send “pass” to the m1 sandbox.  This is how the status is displayed on the mobile IoT app.

Verify a user’s fingerprint against the stored fingerprint:

Click the “vfy_user_mode” switch to change the state from OFF to ON.  A message will appear to indicate that the scanner is ready to scan your fingerprint. When the blue LED on ESP8266 board is turned on, place your fingerprint on the scanner.  Keep your fingerprint until the blue LED is disabled.

If the operation is successful, a message below will be displayed.

If the operation is unsuccessful, a different message will be displayed.   The red led is turned on.

Click the “vfy_user_mode” switch to change the state from ON to OFF.  A message will appear to indicate that it is back to idle mode.

The serial monitor window displays the detail needed to understand the process.  The verification scan is usually a quicker scan than the new user scan.

Delete the existing user’s fingerprint:

Click the “del_user_mode” switch to change the state from OFF to ON.  A message will appear to indicate that the stored fingerprint data is being deleted. When the blue LED on ESP8266 board is turned on, wait until the blue LED is disabled.  In this mode, it is not required to place your finger on the scanner.

If the operation is successful, a message below will be displayed.  Deleting a stored fingerprint data is usually successful.

But, if there isn’t a stored fingerprint data in the scanner’s memory or you have already removed it, then the operation will be unsuccessful this time.   The red led is turned on.

The serial monitor window displays the detail needed to understand the process.

 

Congratulations!  You have successfully completed the Fingerprint Reader tutorial!  To learn more about the Medium One Sandbox and all its capabilities go here [Medium-One-Docs].

Author: Rochelle Drenan