Create and use an Oracle Autonomous Cloud Database from the Command Line

In this post I’ll cover how to create an Oracle Autonomous Cloud Database download the Wallet credentials and connect to the database all from the command line using the OCI-CLI.

After that I’ll include an example of a shell script that I use to setup my Demo environment.

Prerequisites

Get the Compartment OCID

I like to keep all of my work compartmentalized so that I don’t run into conflicts between my (and potentially other people’s) projects.  This means I’ll need to get the OCID of the compartment I want to work in.

Rather than use the Web Console you can run this command to get a list of your available compartments.

Assuming that you already know which compartment you want to work with you can use the --query  parameter to retrieve the ID of that compartment.

The above command returns an array called data that I will use to query an object.

I’d like to retrieve only the object with a name of ‘Demo’.

Now that I have the full object, I can get the id value.

The list command will return all objects that match the query criteria in an array.  Even when there is only a single object it will be returned in an array.

Next, I pipe out the first (and only) value from the array.

Using the --raw-output  parameter, I can get the raw value without the double quotes.

I can use this command to set an environment variable.

The OCI-CLI query parameter uses the JMESPath query language.

Create Compartment

If the compartment doesn’t exist you can use OCI to create one.  For this command you will need the OCID of an existing compartment.  This will be the parent compartment.

If you want to use an existing compartment as a parent, you can use the above command to get the OCID.  Or, if you want to add the new compartment to the ROOT compartment, you can use the Tenancy OCID.

You can get the Tenancy OCID from:

  • Your OCI Config file cat ~/.oci/config.
  • The OCID of an existing compartments parent.
    This time I’m using the ?contains()  function to check compartment-id for the string ‘.tenancy.’.  Notice that the compartment-id must be double quoted because it contains a ‘-‘ and those double quotes are escaped.  \"compartment-id\" oci iam compartment list --query "data[?contains(\"compartment-id\",'.tenancy.')].\"compartment-id\" | [0]" --raw-output

Once you have the parent compartment OCID the command to create a new compartment is:

Database

I can check to see if the database already exists by using a query similar to the one I used for compartments.

If the demo database doesn’t exist I can create a new Always-Free Autonomous Cloud Database with the OCI-CLI.

The data-storage-size-in-tbs is set to 1TB which is larger than the free tier supports.  Setting --is-free-tier True  will cause the system to automatically scale it to the correct size.

The default value for ‘is-free-tier’ is False, if you do not include this parameter you will create a standard Autonomous Cloud Database.  You should check the Cost Estimator to ensure that you’re OK with the cost.

Setting --db-workload "OLTP"  will create an Autonomous Transaction Processing database, using “DW” will create a Data Warehouse.

Make sure you use a strong --admin-password , this will be the admin password for the new database.

This command will return a JSON object with the properties of the new database.

I’ll add the query and raw-output parameters to extract the ID and assign it to an environment variable.

In order to connect to my new database I will need to

Download the Wallet

Wait for your database to be in an AVAILABLE state before attempting to download the wallet.

This command will download your wallet credentials in a .zip file, just like you’d get from the web console.

The $DB_ID variable was set above for the demo database.  The –file parameter accepts the location and file name where you want to download the .zip file.  The new file will have the password set by –password.

Now that everything is in place I can

Test the Connection

  • I’ll start SQLcl without making a connection (/nolog).
  • Set cloudconfig to the location of the wallet credentials.
  • Connect with the admin password and one of the service names contained in the tnsnames.ora file included in the wallet zip file.
    The predefined service names will be in the form of <name of the database>_<performance level> .  You can find more information here.
  • Run a test query.

Use a Shell Script to Automate

The following is an example of a setup script I use for my demos.

Notice that in the create database method I added a new parameter to the OCI call --wait-for-state AVAILABLE.  Since I won’t be able to download the wallet until the database is available, I use this parameter to pause at the create step until the new Database is fully up and running.

When I run the script I get

Explore

This is just a small taste of what you can do with the OCI-CLI.  Check out the documentation for a look at the possibilities.

Leave a comment if you have a question and I will do my best to find you an answer.

Upgrade Oracle Kubernetes Engine on the the Oracle Cloud

Your Oracle Container Cluster is not automatically upgraded to new versions as the come out.  Automatically upgrading your cluster could cause problems if you’re running an application that would fail on a newer version.

However, the process to upgrade your Oracle Container Cluster is fairly straight forward.

Warning

Before you upgrade your Container Cluster, make sure all of your deployed apps will work with the version you intend to upgrade to.

Prerequisites

Open the Cluster details page

From your Oracle Cloud Dashboard

  1. Click the menu icon in the upper left.
  2. Find “Developer Services”.
  3. Click Container Services (OKE).
  4. Select the cluster you want to upgrade.

If there’s an upgrade available you’ll find a button next to the delete button on the details page.  Unfortunately, I had upgraded my cluster before I took a screenshot.  But, I used my amazing image editing skills to add a button to the picture below.

Push the upgrade button and you will see a list of the versions that are available.  You can upgrade 1 version at a time until you get to the current version.   If you’re upgrading across multiple versions, I recommend testing your deployed apps after each upgrade.

Worker Nodes

Worker nodes will not automatically upgrade with the master node.  If you have worker nodes that are more that 2 versions behind the master you will receive an error when you attempt to upgrade the cluster beyond that point.

I’m sure you could upgrade the worker nodes in your node pools manually, but I decided to take the easy route and…

Migrate to New Worker Nodes
  1. In your cluster details page, under resources, click “Node Pools”.
  2. Open your node pool details page.
  3. Under resources click nodes.
  4. For each node, collect the private IP and any custom settings, save them for later.  You could also keep this page open in a separate window.
  5. Go back to your cluster details page, and click the “Add Node Pool” button.
  6. Create a new pool using the same settings for the current pool and its nodes.
  7. Wait until all Nodes are “Ready”.
  8. In a terminal use kubectrl to drain the existing pool.
    Once the current pool is drained, Kubernetes should automatically move all of the pods from the drained pool into nodes in in the new pool.
    If you’ve manually assigned your pods to a specific node, you will need to move the pod manually. (Not covered here.)
  9. Open the Kubernetes API, make sure all of the pods are running on the new pool’s nodes.
  10. Go back to the Oracle Container Cluster details page, under resources, Open the drained node pool.
  11. Click “Delete Node Pool”.
  12. If you have multiple Node Pools, repeat these steps for each pool.

If your cluster was more than 2 versions behind you may have to repeat this process until you’re on the current version.

Install and configure the Oracle Cloud Command Line Interface

I love working with cloud resources.  I don’t have to bog down my laptop and I don’t have to maintain all of the back-end stuff.  I don’t mean to make it sound as if I think the “back-end stuff” is easy.  It’s actually, I understand just enough of that “stuff” to make it go (most of the time) so it’s nice to have experts in the cloud taking care of it for me.

Some of you may be thinking “but cloud resources are expensive.”  That’s true sometimes, but it depends on who’s cloud you’re using.  If you’ve been following me you should already know how much I like Oracle’s Always Free Services and you should know that I love to automate anything I can.  If you’d like to follow along but you don’t have an Oracle Cloud account, click that link, create an Always Free account then come back.

In this post I’ll cover how to use the Oracle Cloud Command Line Interface (OCI-CLI) to access and control your Oracle Cloud resources.

CLI Overview

Oracle’s cloud CLI is a small application you can use to control your Oracle Cloud resources.  It gives you the same core functionality as you’d get using the Web Console, and some extra commands.  It allows you to control your cloud account from your local console application so you can easily automate the control of your resources.

Pre-requisits

Python 3.5+

The CLI is built with Python so make sure you have Python version 3.5 or higher installed.

RSA Key Pair

You will need an RSA key attached to your cloud user in order to remotely access your account.  This must be an RSA key pair in PEM format (minimum 2048 bits).

The easiest way to generate this key par is with openssl.  The following commands work in Linux/Mac environments.  For Windows you can use your favorite tool or execute the commands in GitBash, WSL or some other Linux shell environment.

The first command creates a PRIVATE KEY called ‘myPrivateKey.pem’ (name yours whatever you’d like).  This is the key you will use to access remote systems.  DO NOT share this key, whoever has this key can connect to those systems as you.  Think of it as your admin password.

The second command uses your private key to create a PUBLIC KEY called ‘myPublicKey.pem’ (name yours whatever you’d like).  This is the key you will share with remote systems.  Those systems will add your PUBLIC KEY to their authorized keys list, allowing you to access their system using your private key.

Store these keys in a secure location.  On Linux, the default location is usually in the ~/.ssh directory.  But, if you’re creating separate keys for your projects, you can store them wherever you’d like.  Just remember the location for later.

Cloud Account

You need to have access to an Oracle Cloud account with a user that is authorized to preform the tasks you intend to automate.  A good way to tell if your user has the correct permissions is to log onto your account through the Web Console and create an Always Free database then terminate it.

While you’re logged into the Web Console collect some information.

  1. Tenancy
    1. In the menu, under Administration, click Tenancy Details.
    2. Locate the OCID and click Copy.
    3. Save this value for later.
  2.  User
    1. In the menu under Identity click Users.
    2. Select your user.
    3. Near the bottom click ‘API Keys’ under the resource menu.
    4. Click the ‘Add Public Key’ button.
    5. Choose the PUBLIC key file you generated earlier.
    6. Click the ‘Add’ button.
    7. Your key should now show up in the ‘API Keys’ list.
    8. Copy the fingerprint of your key and save it for later.
    9. Near the top of the user page, locate the OCID and click Copy.  Save this value for later.

Quickstart Install

You can download an execute a script that will ask you typical installation configuration questions, after which it will install and configure the OCI-CLI.

The following is current as of the publish date for this post, but you may want to review the instructions in case things change.

Linux / Mac

Open a terminal and run the following command.

Windows

Open PowerShell as Administrator.

In either system, answer the questions to complete the install.

Install with Python

If you don’t have the rights on your computer or you’d rather not execute the above scripts, you can install the OCI-CLI with Python.

I recommend using a virtual environment when working with python.  It helps keep all of your projects clean and isolated.

Once your virtual environment is active, install the OCI-CLI with pip.

You can see if the install was successful by checking the version.

Configure the OCI-CLI

Using the values you saved from above, you can create a config file with this command.

You will be prompted for the following information.

  • The default location for the config file is typically ‘~/.oci/config’.  If you use a different location you will need to remember where it is.
  • Enter the user and tenancy OCIDs saved from your account.
  • Enter the region you want to work in.  The system will display some examples you can choose from.
  • You already generated an RSA key pair so enter ‘n’.
  • Enter the location of your PRIVATE key.  This will not be uploaded, the CLI will use your PRIVATE key to make the connection to the cloud.
  • Enter the Fingerprint you saved when you uploaded your PUBLIC key.

Once it’s complete, you should see a response similar to this.

Your OCI-CLI should now be configured.  If you open the config file it should look similar to this.

You can add other connection profiles manually by following this format or you can use the same command to add a new profile.  If you re-run the command, it will ask you for a name to use for the new profile which will be added to the config file.

Quick Test

Enter the following command.

If everything is working, you should receive a response similar to this.

Now that your OCI-CLI is installed and configured, you should familiarize yourself with the OCI-CLI documentation to learn about the many, many commands you can use to automate the control of your Oracle Cloud resources.

You can use these same commands from any system with the OCI-CLI installed, including Oracle Cloud Compute instances.

Use ORDS to run the CodeCard backend on your own free Oracle Cloud Database

ORDS (Oracle Rest Data Services) is a fast and easy way to host a REST API you can use to take full control of your Oracle CodeCard.

In this post I’ll walk through how to create the ORDS API on your own Always Free Oracle Cloud Database.

Prerequisites

    1. Create a compartment in your Oracle Cloud Account (Optional but recommended)
    2. Create an Always Free Autonomous Database on the Oracle Cloud
    3. Go to the Service Console for your new database, click on “Development” and save the URL in the “RESTful Services and SODA” section.
    4. CodeCard Sketch changes: Howto disable fingerprint check and increase REST URI size
    5. You Went to Oracle Open World 19 and got a Code Card, now what?
      Ignore the fingerprint settings since you just disabled that in the previous step but add the following.
      Replace the below {{URL}} with the URL you saved above.
      Make sure there’s only one / between your URL and cc.  For example:
      buttona1=https://asdr34edyjtyi4j-codecard.adb.us-ashburn-1.oraclecloudapps.com/ords/cc/functions/master

When all of that is done, go to the Development section of the Service Console for your ATP instance and click “SQL Developer Web”.  Sign in as admin with the admin password you created in step 2.

Database Setup

As Admin, create the CODE_CARD schema.

Execute the following code in the worksheet.  Use a good password and remember it for later.

This will create the new CODE_CARD schema and REST enable the schema so you can use it with ORDS.  Notice the p_url_mapping_pattern is set to ‘cc’, this will be part of the REST URI in the following sections.

oraclecloudapps.com/ords/cc/
As code_card, create the database objects

Switch to the code_card schema by changing the URL In your browser.  Replace ‘admin’ with ‘cc’.
...oraclecloudapps.com/ords/admin/_sdw/?nav=worksheet  to ...oraclecloudapps.com/ords/cc/_sdw/?nav=worksheet

Log into SQL Developer Web as code_card using your new password.

In a worksheet, use the following to create the tables.

Oracle REST Data Services API

You will need two rest endpoints.   One to POST the setting for each button press and one your CodeCard will use to GET those settings.

There are multiple ways you can create an ORDS API, this post will walk through how to create the API using PL/SQL.  I will explain the settings that are most important for the CodeCard interface.  For the other settings, you can find the full documentation here.

This step was completed above

When you created the new schema above, you also REST enabled the new schema with this PL/SQL.

This command was included in the above step so that you could log into SQL Developer WEB as code_card.

The following will explain the individual PL/SQL procedures used to create the REST API.

If you want to skip the explanation, you can jump straight to the complete code included below.

Define a module

A module is a collection of related REST services.  Think of a module as a package that contains REST endpoints.

Create a module called ‘functions’.

The base path is set to ‘/functions/’, this will be part of the REST URI.

oraclecloudapps.com/ords/cc/functions/
Define a Template

A Template is the endpoint for your REST API.

The pattern is set to ‘master’, this will be the final part of the REST URI.

oraclecloudapps.com/ords/cc/functions/master
GET request handler

The CodeCard sends a GET request to the REST API to retrieve the settings assigned to a specific button (A or B) and press function (long or short).

In order to handle this request we need to define a GET handler.

Using a source type of  ‘json/collection’ would allow you to use a simple SQL query and ORDS would handle all of the JSON formatting for us.  This would be easier.

However, we want to be able to return a functioning screen layout to the CodeCard even if there’s an error.  Using a source type of ‘plsql/block’ lets you create and return a custom APEX_JSON object even if there’s an error.

Parameters for the bind variables

The PL/SQL code uses 3 bind variables that are mapped to incoming request header values.

The bind variables are mapped to the header values by defining parameters. These parameters will all be assigned to the ‘functions’ module, ‘master’ template and  ‘GET’ handler.  They will be passed ‘IN’ through the ‘HEADER’ as a ‘STRING’ type.  The value of the incoming header defined in ‘p_name’ will be mapped to value of the PL/SQL bind variable defined in ‘p_bind_variable_name’.

  • X-CODECARD-ID is the id assigned to your CodeCard.
  • X-CODECARD-BUTTON-LABEL will either be the A or B button.
  • X-CODECARD-BUTTON-FUNCTION will be 1 for a short press or 2 for a long press.
Handle POST requests

The CodeCard sends a POST request to the REST API to store the settings assigned to a specific button and press function.

In order to handle this request we need to define a POST handler.

This PL/SQL block will either create a new record or update an existing record for the incoming CodeCard id, button label and button function.

Parameters for the bind variables

The parameters for the POST handler are the same as for the GET handler.

Register template (Optional)

The register template is used by the CodeCard designer to map your name to your CodeCard id, if you choose to enter it.  Another post will detail how to install the CodeCard designer in an always free Oracle compute instance.  If you plan on implementing the designer, include this handler template and handler.  Even if you do not plan on implementing the designer, it won’t hurt anything to include these objects.

If you are piecing all of the above sections together you will need to execute a ‘COMMIT’ to save the changes to your database.  Or, you can use the following.

Full ORDS PL/SQL code

In a worksheet use the following code to create the Oracle REST Data Services API.

Setup a button press

One final piece of information you’ll need is your CodeCard’s id.

  1. Turn your CodeCard on.
  2. Press and release the A and B buttons at the same time.  Your CodeCard will display a barcode with a 12 character id string under it.
  3. Save that ID string.

Testing

POST

If you are using a tool such as Postman to test your API you will need to create a POST request with the following pieces.

  • URI:  {{URL from the prerequisite section}}/cc/functions/master
    For example: https://asdr34edyjtyi4j-codecard.adb.us-ashburn-1.oraclecloudapps.com/ords/cc/functions/master
  •  Headers
    • X-CODECARD-ID: Us the ID string from above
    • X-CODECARD-BUTTON-LABEL:  either ‘a’ or ‘b’
    • X-CODECARD-BUTTON-FUNCTION: use ‘1’ for a short press or ‘2’ for a long press
    • Content-Type: application/json
  • Body: use a JSON object like this
     

If you’d prefer to use a CURL command (replace the {{ }} sections with your values):

With either method, you should receive a response with a status of 200 and a JSON object in the body like this

Test GET

Assuming you completed the prerequisite section, you should be able to short or long press the A or B button on your CodeCard and your new template settings will be displayed on your screen.

You can also test the GET handler by sending a GET request to the same URI used above.  Use the same values for the headers, you do not need a body.

  • X-CODECARD-ID: Use the ID string from above
  • X-CODECARD-BUTTON-LABEL:  either ‘a’ or ‘b’
  • X-CODECARD-BUTTON-FUNCTION: use ‘1’ for a short press or ‘2’ for a long press

If you’d rather use CURL (replace the {{ }} sections with your values):

You should receive a JSON object like the one you sent in the body of your POST.

If the GET request works but your CodeCard doesn’t, go back to the prerequisite section and make sure you followed steps 4 and 5 correctly.

Have Fun

Once you get everything working you could experiment with changing the ORDS GET handler to do something else when a button is pressed.

  • Create a new table and log which button is pressed and if it’s a short or long press.
  • Run a query on a table and return the results in the bodytext.  (There are some size limits.)
  • Execute a stored procedure that does whatever you want it to do.
  • Make a different module/template/GET API for each button/press.

Create an Always Free Autonomous Database on the Oracle Cloud

You’ve signed up for the Oracle Cloud Free Tier at https://www.oracle.com/cloud/free/ and now you want to create an Always Free Autonomous Database.

Create a new Database

These instructions should work for both (ATP) Autonomous Transaction Processing and (ADW) Autonomous Data Warehouse Databases.

After you log into your Oracle Cloud Dashboard.

  1. Click on the “Create an ATP database” box. (Or the “Create an ADW database” box if you want a data warehouse)
  2. Choose the compartment you want to use.
  3. Fill in the “Display Name” field.  This name will be displayed in the GUI lists and drop down selection boxes in your Oracle Cloud dashboard.  You can change this later.
  4. Fill in the “Database Name” field.  This name will be used as the permanent ID for this database.  It will show up in places such as the auto-generated TNSNAMES.ORA file that you’ll download in another step.  You can not change this later, so choose wisely.
  5. In the “Choose a workload type” section, make sure the correct workload type is selected..
  6. Since we want to create an Always Free Database, leave “Shared Infrastructure” selected in the “Choose a deployment type” section.
  7. Make sure the “Always Free” selector is turned on.  This will lock in the options for an Always Free instance.  (20 GB of storage and 1 OCPU)
  8. Scroll down to the “Create administrator credentials” section and enter a Strong password for your Admin account.
    You will use the Admin account to connect to your Autonomous Database instead of SYS or System.
  9. Under the “Choose a license type” section make sure “License Included” is selected.
  10. Click the “Create Autonomous Database” button.

Your new ATP instance will be provisioned.  The orange box will turn green once it has been provisioned and is available to use.

While you’re waiting, check that you see the Always Free tag next to your database name.  If you do not see the tag, you may want to check to see what license you created the instance under and make sure you are OK with those options or terminate the instance and create a new one with the Always Free options selected.

Once the orange box turns green and your database is available, you will want to connect to it.

The Oracle Autonomous Cloud Databases are setup with a little extra security.  In order to connect you will need to use a wallet credentials file.

Download the Oracle Credentials file

There are a couple different ways to get the wallet file through the Cloud Dashboard.

From the Details page
    1. Click on the “DB Connection” button.
    2. On this form you will find a list of the auto-generated TNSNAMES entries and connection strings that you can use to connect to your database.  There is a link to the documentation explaining the difference between the entries.  For typical transactions I like to use the one ending in _TP.
    3. Click the “Download Wallet” button.
    4. Create a password that will be used to access the .zip file.
    5. Click the “Download” button.

      Remember the location where you save your wallet file, you will need it when we test the connection.
    6. Save the .zip file to a secure location.  This file is used to access your database so keep it secure.
From the Service Console

You can get to the Service Console for your Database instance either from the Details page

or from the menu for the instance in the Autonomous Transaction Processing Database list.

Once your in the service Console

  1. Click on “Administration”.
  2. Click on “Download Client Credentials (Wallet)”.
  3. Create a password that will be used to access the .zip file.
  4. Click the “Download” button.
Important Wallet Security Information

All wallets downloaded with either method will create a copy of the *SAME WALLET* even if you use different passwords for the .zip file.

You can rotate the wallet from your database instance details page.  Read the docs.

  1. Click the “DB Connection” button.
  2. Press the “Rotate Wallet” button and follow the instructions.

Connect to the Database

SQLcl is a great tool for making a quick and easy connection to the new database.

  1. Start SQLcl in ‘nolog’ mode
  2. Set the location of your .zip file in the cloudconfig variable.
  3. Connect to your database using the password you set for the Admin account.
  4. Run a test query

Enjoy

Your new Always Free Oracle Autonomous Database is running and you are able to connect.  Now you can start building your application.

If you have an questions please post them in the comments and I’ll do my best to help you find an answer.

Create an Always Free Compute VM on the Oracle Cloud

You’ve signed up for an Oracle Cloud Free Tier at https://www.oracle.com/cloud/free/ and now you want to deploy an app to a virtual machine compute instance.

Prerequisite

You will need an SSH key pair.  You can use an existing key or you can generate a new one.

Create a new Compute instance

After you log into your Oracle Cloud Dashboard.

  1. Click on the “Create a VM instance” box
  2. In the form that opens, you can give your new instance a name that makes sense for your project or use the default name
  3. Click “Show Shape, Network and Storage Options”
  4. Make sure that the Always Free options are selected for:
    1. Availability Domain
    2. Instance Type
    3. Instance Shape
  5. Choose the compartment you want to use for your cloud network objects for both:
    (If you have not created a Virtual cloud network in your selected compartment, the system will create it for you.)

    1. Virtual cloud network compartment
    2. Subnet compartment
  6. If you would like a public IP assigned when the instance is created select the option “Assign a public IP address”
  7. In the “Add SSH key” section you can add your SSH public key using one of these methods:
    1. Uploading the file with the “Choose File” button
    2. Copying and pasting the key into the text field
    3. Drag the public key file into the “Drop Files Here” box
  8. Click “Show Advanced Options”
  9. Select the Compartment you would like to use for your new Compute instance
  10. Click the “Create” button

Your new Compute instance will be provisioned.  The Orange box will turn Green when it has been provisioned and is available to use.

Look in the “Instance Information” tab, in the “Primary VNIC Information” section and get your assigned “Public IP Address”.

Test with SSH

You will want to look up the best way to open an SSH connection for your operating system.

The default user that you will connect as is “OPC”.

On Linux you can test your connection using the following command:

You should see the following question asking if you are sure you want to connect to this new instance.  This should only happen the first time you establish a connection to this instance from this machine.

Type “yes” and hit enter.

You should now be connected to your new instance and can start setting it up to deploy your application.

Create a compartment in your Oracle Cloud Account

Whenever I’m working on a project, I like to keep the related objects grouped together and separated from other projects, to make my life easier.

Oracle cloud helps you to do this with compartments and making them is pretty easy.

I’m using an Oracle Cloud Free Tier for my example, if you don’t have an account you can get one at https://www.oracle.com/cloud/free/

After you log into your Oracle Cloud Dashboard.

  1. Open the Menu
  2. Scroll down and click Identity
  3. Click on Compartments
  4. Click on the Create Compartment button
  5. Fill in Name and Description
  6. Choose a parent compartment or leave it set to the root compartment
  7. Click the ‘Create Compartment’ button

Now when you create a new object such as an Autonomous Database or a Compute instance you can keep them organized in your new compartment.

 

CodeCard Sketch changes: Howto disable fingerprint check and increase REST URI size

Pre-Requisites

  • You have followed the instructions here.
  • You are comfortable using the Arduino IDE and making changes to the Sketch.

Fingerprint Check

In the comments on the post You Went to Oracle Open World 19 and got a Code Card, now what? we talked about how to update the fingerprint of the security certificate for the REST API when it changes.

I’m not a big fan of doing things multiple times and since I’m not planning on doing anything of a sensitive nature with my CodeCard I decided I would just disable the fingerprint check altogether.

How to tell if the fingerprint check is causing your badge to stop working.

If you push one of the buttons and it hangs on the “Please wait…” screen forever, check the Serial Monitor for a message similar to this.

Warning, If you’re planning to use your CodeCard for anything you’d consider sensitive, do not make this change!

Upgrade the driver

  1. Clone or download the CodeCard repository
  2. In the Arduino IDE, open the file codecard/arduino/codecard/codecard.ino
  3. Open the Board Manager.  Tools/Board/Boards Manager
  4. Search for esp
  5. Select version 2.5.2
  6. Click Install
  7. Close the Boards Manager
Code Changes
  • Click on the httpClient.h tab
  • Replace line 74 with BearSSL::WiFiClientSecure client;

  • On line 102 add client.setInsecure();

  • Comment out the fingerprint check starting on line 112

  • Uncomment line 152 and remove line 153

  • On line 176 add secureClient.setInsecure();

  • Comment out the fingerprint check starting on line 185

Increase arrayToStore variable size

If you’re planning to change the REST calls to use a different and longer URI you will want to increase the size of the arrayToStore variables.  Currently they are set to 100, I changed mine to 200, but you can use whatever you’d like.

  • Click on the memory.h tab
  • On lines 18 and 46, change the arrayToStore variable to the new size
  • Click on the wifi.h tab
  • On line 7, change the arrayToStore variable to the new size

Troubleshooting

Sketch uses too much program storage space

I have seen this error off and on when I compile the sketch.  If you get this error, the easiest way to reduce the size of the sketch is to remove some of the larger icons in icons.h.

  • Click on icons.h
  • Find a 128x128px image that you don’t plan to use and either comment it or remove it.
  • Click on templates.h
  • Find the drawIcon128(int x, int y, String icon, long color) method and comment or remove the reference to the image you removed.
  • You may have to remove more than one image.
“Connection failed” or you receive an empty response “{}”

This one can be tricky.  The way I’ve solved this is to erase the ESP8266 flash memory.

Usually this works:

  • Connect with the Serial Monitor
  • Press and release the A and B buttons
  • Wait for the Serial Monitor to display all of the data
  • Enter “reset” and send
  • Enter “ls” and update any settings as needed

If that doesn’t work you may need to search for another way to reset the memory.  Please leave a comment if you have a better way.

 

You Went to Oracle Open World 19 and got a Code Card, now what?

We handed out several hundred Code Cards this year and I’m guessing a few of you are wondering what to do next.

If you got home and pressed one of the buttons you more than likely saw this screen.

Don’t worry, it’s not broken, you just need to get it connected to the internet.  There are a few different ways to do this.

Note: The Code Card uses a 2.4 GHz WiFi connection.

Create a WiFi Network

The easiest way to get it connected is to create a WiFi network using the credentials that are already set on the Code Card.

One way you can do this is to create guest network on your WiFi router.  Please refer to your router manual for instructions on setting this up.

Alternatively, you could create a hotspot on your phone, but make sure you’re OK with any charges from your service provider.

Edit:

At Oracle we like to keep everything patched and up to date.  After I published this post, the security certificate for the REST back end was updated.  This means you will also need to update the fingerprint settings for the four button options.

This also means that creating a WiFi SSID as in the paragraph above will only work if you also update the following four settings.  For that you’ll need to choose one of the methods below.   (I have added them to the examples below.)

Change the WiFi credentials on the card

If you’d rather just connect the Code Card to your existing WiFi network (2.4 GHz only), you can change the settings on the card.

In order to do this you need to open a serial connection to the card and send the following commands (using your WiFi credentials):

A Little Python

If you’d like to use Python:

  1. Install Python 3 if you don’t already have it.
  2. Open a terminal and install pyserial.
  3. Create a file using the following code.  I named mine ccSerial.py.
  4. Change lines 7 and 8 to use your WiFi credentials.
  5. In the terminal run the new module and follow the instructions.
    You should see something similar to the following.
Arduino IDE

If you have a Serial communication tool that you like, you should be able to use it to change the settings.

If not the Arduino IDE includes a Serial Monitor tool that work great.

  1. Do not connect your Code Card to the computer yet.
  2. Download, install and run the Arduino IDE.
  3. Click on Tools / Port.
  4. See what Ports are already in use.
  5. Connect your Code Card and turn it on.
  6. Click on Tools / Port.
  7. The newest Port should be your Code Card; select it.
  8. Click on Tools / Serial Monitor.
  9. On the bottom of the Serial Monitor, choose 115200 baud.
  10. Turn your Code Card off and on again.
  11. Press and release the A and B buttons at the same time.
    You should see something like this.