Forem: Peter Okwara

Minting an NFT on an android app (Part 1)

Peter Okwara — Fri, 02 Dec 2022 13:36:37 +0000

Introduction

Non-fungible means that something is unique and cannot be replaced by something else. Blockchains like Ethereum, polygon, and Iota act as a source of truth and help keep track of who's holding and trading NFTs

NFT's have multiple use cases, from Music, Fashion, Gaming, Luxury goods, Metaverse, Supply chain, and Ticket Sales. Nike recently partnered with Polygon to launch a web3 platform for NFTs in the form of digital shoes https://decrypt.co/114494/nike-swoosh-web3-platform-polygon-nfts

Most online blogs demonstrate how to mint an NFT using a web application. In this blog, we will be minting an NFT via an android app. The mobile app will be partly Java and, Kotlin.

The full working code can be found here

Prerequisite

The requirements are:

Web3j: Lightweight Java and Android library for integration with Ethereum clients. https://www.web3labs.com/web3j-sdk
Android Studio: Official integrated development environment for Google's Android operating system. https://developer.android.com/studio
Truffle: Smart contract development tool. https://trufflesuite.com
Ngrok: A reverse proxy service for fronting your web service. https://ngrok.com/

1. Create the smart contract

Create a new truffle project by running.

truffle init

Install openzeppelin within the truffle project by running.

npm install --save-dev @openzeppelin/contracts

Create a smart contract in the contract/ directory called lemurNFT.sol.

// SPDX-License-Identifier: MIT
pragma solidity >=0.4.22 <0.9.0;

import "openzeppelin-solidity/contracts/token/ERC721/ERC721.sol";
import "openzeppelin-solidity/contracts/utils/Counters.sol";
import "openzeppelin-solidity/contracts/token/ERC721/extensions/RRERC721URIStorage.sol";

contract lemurNFT is ERC721URIStorage {
    using Counters for Counters.Counter;
    Counters.Counter private _tokenIds;

    constructor() public ERC721("lemurNFT", "LMR") {}

    function mintNFT(address recipient, string memory tokenURI)
        public
        returns (uint256)
    {
        _tokenIds.increment();
        uint256 newItemId = _tokenIds.current();
        _mint(recipient, newItemId);
        _setTokenURI(newItemId, tokenURI);

        return newItemId;
    }

Within the smart contract:

_tokenIds.increment(): Increase the counter by 1, thus enabling the code to generate a unique Token ID.
uint256 newItemId = _tokenIds.current() assigns the current count number to a new instance of _tokenIds named newItemId.
_safeMint(recipient, newItemId) mints newItemId and assigns it to recipient (an address).
_setTokenURI(newItemId, tokenURI) sets tokenURI of the NFTs metadata file, that we created earlier.

2. Set up the development environment

Configure the truffle-config.js file to use the development environment by adding or commenting out the following section. Ensure WebSockets are enabled. This is because we will connect to our node via WebSockets.

  development: {
      host: "127.0.0.1", // Localhost (default: none)
      port: 8545, // Standard Ethereum port (default: none)
      network_id: "*", // Any network (default: none)
      websocket: true, // Enable EventEmitter interface for web3 (default: false)
    }

3. Deploy the smart contract

To compile the smart contract, run

truffle compile

The output should look something similar to

Compiling your contracts...
===========================
> Compiling .\contracts\Migrations.sol
> Compiling .\contracts\lemurNFT.sol
> Compiling openzeppelin-solidity\contracts\token\ERC721\ERC721.sol
> Compiling openzeppelin-solidity\contracts\token\ERC721\IERC721.sol
> Compiling openzeppelin-solidity\contracts\token\ERC721\IERC721Receiver.sol
> Compiling openzeppelin-solidity\contracts\token\ERC721\extensions\ERC721URIStorage.sol
> Compiling openzeppelin-solidity\contracts\token\ERC721\extensions\IERC721Metadata.sol
> Compiling openzeppelin-solidity\contracts\utils\Address.sol
> Compiling openzeppelin-solidity\contracts\utils\Context.sol
> Compiling openzeppelin-solidity\contracts\utils\Counters.sol
> Compiling openzeppelin-solidity\contracts\utils\Strings.sol
> Compiling openzeppelin-solidity\contracts\utils\introspection\ERC165.sol
> Compiling openzeppelin-solidity\contracts\utils\introspection\IERC165.sol
> Compilation warnings encountered:

    Warning: Visibility for constructor is ignored. If you want the contract to be non-deployable, making it "abstract" is sufficient.
  --> project:/contracts/lemurNFT.sol:12:5:
   |
12 |     constructor() public ERC721("lemurNFT", "LMR") {}
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


> Artifacts written to C:\Users\peter\Documents\GitHub\lemur-nft\contract\build\contracts
> Compiled successfully using:
   - solc: 0.8.13+commit.abaa5c0e.Emscripten.clang

Run a local node by running

ganache

The output should look something similar to

ganache v7.5.0 (@ganache/cli: 0.6.0, @ganache/core: 0.6.0)
Starting RPC server

Available Accounts
==================
(0) 0x42703e1F2CCB08583088D96d71d4549Be08b52a7 (1000 ETH)
(1) 0x859e7f120E751C505EB14C942A192eC3448a12a1 (1000 ETH)
(2) 0x2864E9c62dE39c44a97866D31546069fD86DF71E (1000 ETH)
(3) 0x656d2d16C6ad06677A9A87e105e786E9f0420d5c (1000 ETH)
(4) 0x70BDc8926bb41e3a778e3F812Fe18db181aa2602 (1000 ETH)
(5) 0x05A2e3a72a63D2e0A85c7259E3aD6A5b9773cb79 (1000 ETH)
(6) 0x135A6788B85973890d11AdED97a76BfD5acd9F37 (1000 ETH)
(7) 0x19fCd2F3F957b9761e52C5583A14CE2669bbF257 (1000 ETH)
(8) 0xaf47CA6B33E5b895E68D937fDb2CaEEB4e462845 (1000 ETH)
(9) 0x61cDEbBCc8579560A79aaA41936fc553E22615E2 (1000 ETH)

Private Keys
==================
(0) 0xbea5ebe59d051534239ec8e81018b9d2f8458eee5864584d9d520a0c4307de90
(1) 0x5c0fd2fc115d1ab0c8e0ab3f367ac68dcb6e8e9c037a7de791cfba3d50dff993
(2) 0x3d0f2dc97eb7203213c42363f2f2fad34aa4bd0d1029347e72dfad41f900bc2c
(3) 0xa697dc1f7e4d08e899bdbdef17b303048d425bb7bfa712653071f4270fef6a7b
(4) 0x9dd1cccefa2486212ac11cd451d36de3a956ae2be9d4740783b55f94053fa837
(5) 0x1044bba3f188578d08a5c36aae4d4f0bacbfaa60e31e2b96791e5c2b099278a6
(6) 0x02314898ed8983c1c3598e74757bb3e933d4506e4d238706938479f756da8b94
(7) 0x7a7988d32c9a7ab50a9d4d4a9bf5ddf05db49cf2a0f5e196b5fb076d183f4bec
(8) 0xaac1f5cfc3c8ad7c2ed6eb843e0412668e00b4f87e82341bd6090239acb561fe
(9) 0x5b072abfa5a17d7a88fe456867789d0ba97c625e1c969485921765301c916b90

HD Wallet
==================
Mnemonic:      truth manual elephant border predict castle payment suspect mimic insect wish acoustic
Base HD Path:  m/44'/60'/0'/0/{account_index}

Default Gas Price
==================
2000000000

BlockGas Limit
==================
30000000

Call Gas Limit
==================
50000000

Chain Id
==================
1337

RPC Listening on 127.0.0.1:8545

Make sure you keep the process running. Store the seed in a secure place, it will be needed later for the android app. Don�t use the private keys or seed anywhere else or you risk being hacked.

The mnemonic (truth manual elephant border predict castle payment suspect mimic insect wish acoustic) will be used when setting up the android configuration.

We will also use the first public address 0x42703e1F2CCB08583088D96d71d4549Be08b52a7 as the wallet address.

Run the development command to deploy the smart contract.

truffle migrate --network development

If successful, it should show

Compiling your contracts...
===========================
> Compiling .\contracts\Migrations.sol
> Compiling .\contracts\lemurNFT.sol
> Compiling openzeppelin-solidity\contracts\token\ERC721\ERC721.sol
> Compiling openzeppelin-solidity\contracts\token\ERC721\IERC721.sol
> Compiling openzeppelin-solidity\contracts\token\ERC721\IERC721Receiver.sol
> Compiling openzeppelin-solidity\contracts\token\ERC721\extensions\ERC721URIStorage.sol
> Compiling openzeppelin-solidity\contracts\token\ERC721\extensions\IERC721Metadata.sol
> Compiling openzeppelin-solidity\contracts\utils\Address.sol
> Compiling openzeppelin-solidity\contracts\utils\Context.sol
> Compiling openzeppelin-solidity\contracts\utils\Counters.sol
> Compiling openzeppelin-solidity\contracts\utils\Strings.sol
> Compiling openzeppelin-solidity\contracts\utils\introspection\ERC165.sol
> Compiling openzeppelin-solidity\contracts\utils\introspection\IERC165.sol
> Compilation warnings encountered:

    Warning: Visibility for constructor is ignored. If you want the contract to be non-deployable, making it "abstract" is sufficient.
  --> project:/contracts/lemurNFT.sol:12:5:
   |
12 |     constructor() public ERC721("lemurNFT", "LMR") {}
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


> Artifacts written to C:\Users\peter\Documents\GitHub\lemur-nft\contract\build\contracts
> Compiled successfully using:
   - solc: 0.8.13+commit.abaa5c0e.Emscripten.clang


Starting migrations...
======================
> Network name:    'development'
> Network id:      1668618749782
> Block gas limit: 30000000 (0x1c9c380)


1_deploy_contract.js
====================

   Deploying 'lemurNFT'
   --------------------
   > transaction hash:    0xbe14c78e8b59c002e2537a3cbc9a4f616fbbddafd94f4722a59c719d42137860
   > Blocks: 0            Seconds: 0
   > contract address:    0x129Ff5b9D7C128527F3Be5ca5fb4F2E7A991482d
   > block number:        1
   > block timestamp:     1668618761
   > account:             0x7b2D85916C1fc56BBa4706DF0cE1D86532fB3839
   > balance:             999.99153599275
   > gas used:            2507854 (0x26444e)
   > gas price:           3.375 gwei
   > value sent:          0 ETH
   > total cost:          0.00846400725 ETH

   > Saving artifacts
   -------------------------------------
   > Total cost:       0.00846400725 ETH


1_initial_migration.js
======================

   Deploying 'Migrations'
   ----------------------
   > transaction hash:    0x7d4912cdabd080e6d49d0b244a88f86de933f61d491c76ef2847c133626e2d11
   > Blocks: 0            Seconds: 0
   > contract address:    0x12365fE3BA0F866A6E392BD3614B4322D73244C3
   > block number:        2
   > block timestamp:     1668618762
   > account:             0x7b2D85916C1fc56BBa4706DF0cE1D86532fB3839
   > balance:             999.990714509168638856
   > gas used:            250154 (0x3d12a)
   > gas price:           3.283911436 gwei
   > value sent:          0 ETH
   > total cost:          0.000821483581361144 ETH

   > Saving migration to chain.
   > Saving artifacts
   -------------------------------------
   > Total cost:     0.000821483581361144 ETH

Summary
=======
> Total deployments:   2
> Final cost:          0.009285490831361144 ETH

Ensure that you store the contract address (in this example 0x129Ff5b9D7C128527F3Be5ca5fb4F2E7A991482d), located under 1_deploy_contracts since we will use this as the contract address when setting up the configurations for android.

4. Setting up a WebSocket

Before you perform this step, ensure that ganache is running. Once ganache is running, run the command:

ngrok http 8545

Ngrok will act as a forward proxy. It will expose the local network 127.0.0.1:8085 and give you a web address you can use to connect your android app to. The response should look like this:


ngrok

Add Okta or Azure to protect your ngrok dashboard with SSO: <https://ngrok.com/dashSSO>

Session Status:         online
Account:                P.Okwara (Plan: Free)
Version:                3.1.0
Region:                 United States (us)
Latency:                265ms
Web Interface:          http://127.0.0.1:4040
Forwarding:             <https://550b-105-163-1-231.ngrok.io> -> http://localhost:8545
Connections:            ttl opn rt1 rt5 p50 p90 0 0 0.00 0.00 0.00 0.00

We will use the forwarding address https://550b-105-163-1-231.ngrok.io as the websocket url. When adding to the config, we will change https: to wss so that the URL we will use in the end will look like this:

wss://550b-105-163-1-231.ngrok.io

5. Configure the metadata of your NFT using IPFS

Our lemurNFT smart contract function takes in a tokenURI parameter that should resolve to a JSON document describing the NFTs metadata, which is really what brings the NFT to life, allowing it to have configurable properties, such as a name, description, image, and other attributes.

The Interplanetary File System (IPFS) is a decentralized protocol and peer-to-peer network for storing and sharing data in a distributed file system.

We will use Pinata, a convenient IPFS API and toolkit, to store our NFT asset and metadata and ensure that our NFT is truly decentralized. If you don't have a Pinata account, sign up for a free account here.

Once you've created an account:

Navigate to the Pinata Upload button on the top right
Upload an image to pinata - this will be the image asset for your NFT. Feel free to name the asset whatever you wish
After you upload, at the top of the page, there should be a green popup that allows you to view the hash of your upload ---> Copy that hashcode. You can view your upload at: https://gateway.pinata.cloud/ipfs/https://gateway.pinata.cloud/ipfs/<

In your root directory, make a new file called nft-metadata.json and add the following json code:
nft-metadata.json

{
    "attributes" : [ {
      "trait_type" : "Breed",
      "value" : "Maltipoo"
    }, {
      "trait_type" : "Eye color",
      "value" : "Mocha"
    } ],
    "description" : "The world's most adorable and sensitive pup.",
    "image" : "https://gateway.pinata.cloud/ipfs/QmWmvTJmJU3pozR9ZHFmQC2DNDwi2XJtf3QGyYiiagFSWb",
    "name" : "Ramses"
}

Feel free to change the data in the json. You can add or remove attributes. Most importantly, make sure the image field points to the location of your IPFS image otherwise, your NFT will not include a photo.

Once you're done editing the json file, save it and upload it to Pinata, following the same steps we did for uploading the image.

Remember the metadata.json you uploaded to Pinata? Get the hashcode from Pinata. We will use this hash and the url for the next step.

Minting an NFT on an android app (Part 2)

Peter Okwara ・ Dec 2 '22

#android #web3 #blockchain #ipfs

Minting an NFT on an android app (Part 2)

Peter Okwara — Fri, 02 Dec 2022 13:35:52 +0000

6. Set up the config

Create a new blank android project. Within the home directory, create a file called apikey.properties. We will then add the values obtained from the previous steps.

WALLET_ADDRESS="0x42703e1F2CCB08583088D96d71d4549Be08b52a7" 
CONTRACT_ADDRESS="0x129Ff5b9D7C128527F3Be5ca5fb4F2E7A991482d" 
WEB_SOCKET_URL="[wss://550b-105-163-1-231.ngrok.io](https://550b-105-163-1-231.ngrok.io)"
SEED="truth manual elephant border predict castle payment suspect mimic insect wish acoustic"
TOKEN_URI=""

For a recap:

We obtained the WALLET_ADDRESS by taking the first public key after running the ganache command.
We obtained the CONTRACT_ADDRESS after running truffle migrate --network development and taking the contract address from the 1_deploy_contract.js section.
We obtained the SEED after running the ganache command and obtaining the seed generated.

Within the build.gradle (module) under dependencies, add the _web3j _library.

// Add support for web3j
    implementation 'org.web3j:core:4.8.7-android'

Add the configurations within the defaultConfig section of the build.gradle file.

 // Load configuration from the apikey.properties file
 buildConfigField("String", "WALLET_ADDRESS", apikeyProperties['WALLET_ADDRESS'])
 buildConfigField("String", "CONTRACT_ADDRESS", apikeyProperties['CONTRACT_ADDRESS'])
 buildConfigField("String", "WEB_SOCKET_URL", apikeyProperties['WEB_SOCKET_URL'])
 buildConfigField("String", "SEED", apikeyProperties['SEED'])
 buildConfigField("String", "TOKEN_URI", apikeyProperties['TOKEN_URI'])

Do not forget to add internet permissions within the AndroidManifest.xml file by adding the line below to the <application tag.

<uses-permission android:name="android.permission.INTERNET" />

7. Develop the android wrapper

Using the _web3j _library, we can convert our solidity file into a java so that we can call the methods we have written in the solidity file.

web3j generate truffle --truffle-json .\build\contracts\lemurNFT.json -o ..\android\app\src\main\java\ -p com.example.lemur

After running this command successfully, a new java file LemurNFT.java will be generated. Place the file close to the MainActivity.kt file.

8. Create the UI

The user interface is pretty simple, we have a button called MINT. When the button is clicked, it runs the mintNFT _function in the _MainActivity.kt file.

<Button
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:onClick="mintNft"
    android:text="@string/button_text"
    tools:layout_editor_absoluteX="161dp"
    tools:layout_editor_absoluteY="407dp" />

The whole activity_main.xml file looks like this:

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <TextView
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="LemurNFT"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" />

    <Button
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:onClick="mintNft"
        android:text="@string/button_text"
        tools:layout_editor_absoluteX="161dp"
        tools:layout_editor_absoluteY="407dp" />

</androidx.constraintlayout.widget.ConstraintLayout>

The app should look like this:

9. Adding global variables

In your MainActivity.kt add the following variables as global.

// inside of any of your application's code
var walletAddress: String = BuildConfig.WALLET_ADDRESS;
var contractAddress: String = BuildConfig.CONTRACT_ADDRESS;
var webSocketUrl: String = BuildConfig.WEB_SOCKET_URL;
var seed: String = BuildConfig.SEED;
var tokenUri: String = BuildConfig.TOKEN_URI;
private lateinit var credentials: Credentials;

This code loads all the configuration files from our _apikey.properties _file and the BuildConfig file.

We also have a credentials variable that will be initialized later on, and that is globally accessible by any function.

10. Load the credentials

Within the MainActivity.kt file add the following line of code.

/***
 * Create credentials from a seed.
 */
fun loadCredentials(){
    val masterKeypair = Bip32ECKeyPair.generateKeyPair(MnemonicUtils.generateSeed(seed, ""))
    val path = intArrayOf(44 or HARDENED_BIT, 60 or HARDENED_BIT, HARDENED_BIT, 0, 0)
    val x = Bip32ECKeyPair.deriveKeyPair(masterKeypair, path)
    this.credentials = Credentials.create(x)
}

This generates a keypair (a public and private key) to sign our transactions.

11. Load the credentials

Within the MainActivity.kt file add the following line of code.

/***
 * Create credentials from a seed.
 */
fun loadCredentials(){
    val masterKeypair = Bip32ECKeyPair.generateKeyPair(MnemonicUtils.generateSeed(seed, ""))
    val path = intArrayOf(44 or HARDENED_BIT, 60 or HARDENED_BIT, HARDENED_BIT, 0, 0)
    val x = Bip32ECKeyPair.deriveKeyPair(masterKeypair, path)
    this.credentials = Credentials.create(x)
}

This generates a keypair (a public and private key) to sign our transactions.

12. Show the response

We need to show the response after posting the transaction to the blockchain. With this, we will use a toast notification. Add the following code to the MainActivity.kt file.

/**
 * Display the response as a toast notification.
 */
private fun showResponse(response: String){

    val duration  = Toast.LENGTH_LONG;
    val toast = Toast.makeText(applicationContext, response, duration);
    toast.show();

}

The function takes in a string and displays it in a toast notification.

13. Mint an NFT

Here the mintNft function is tied to a button in the main user interface. Once the button is clicked:

The credentials will be loaded from the loadCredentials() function.
A new instance of web3j instance will be created which will be used to connect to the node.
We then load the smart contract which is the LemurNFT contract and provide the contract address, the WebSocket connection, the credentials, and the gas for the transactions.
We then call the smart contract function to mint an NFT, providing the wallet address to mint an NFT to, and the tokenURI.
We then log out the response using Log.e *and *also display the response through a toast notification.

/**
 * Mint an nft when the mint button is clicked.
 */
fun mintNft(view: View) {
    try {
        loadCredentials();
        val web3j: Web3j = createWeb3j()

        val nft: LemurNFT = LemurNFT.load(contractAddress, web3j, credentials, DefaultGasProvider())
        val transactionReceipt: TransactionReceipt = nft.mintNFT(walletAddress, tokenUri).send()

        Log.e("Response", transactionReceipt.toString());
        showResponse(transactionReceipt.toString());

    } catch (e: Exception){
        e.printStackTrace();
    }
    return;
}

The MainActivity.kt will then look like this:

package com.example.lemur

import android.os.Bundle
import android.util.Log
import android.view.View
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import org.web3j.crypto.Bip32ECKeyPair
import org.web3j.crypto.Bip32ECKeyPair.HARDENED_BIT
import org.web3j.crypto.Credentials
import org.web3j.crypto.MnemonicUtils
import org.web3j.protocol.Web3j
import org.web3j.protocol.core.DefaultBlockParameterName
import org.web3j.protocol.core.methods.response.EthGetBalance
import org.web3j.protocol.core.methods.response.TransactionReceipt
import org.web3j.protocol.websocket.WebSocketService
import org.web3j.tx.gas.DefaultGasProvider
import java.math.BigInteger
import java.net.ConnectException


class MainActivity : AppCompatActivity() {

    // inside of any of your application's code
    var walletAddress: String = BuildConfig.WALLET_ADDRESS;
    var contractAddress: String = BuildConfig.CONTRACT_ADDRESS;
    var webSocketUrl: String = BuildConfig.WEB_SOCKET_URL;
    var seed: String = BuildConfig.SEED;
    var tokenUri: String = BuildConfig.TOKEN_URI;
    private lateinit var credentials: Credentials;


    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
    }

    /**
     * Mint an nft when the mint button is clicked.
     */
    fun mintNft(view: View) {
        try {
            loadCredentials();
            val web3j: Web3j = createWeb3j()

            val nft: LemurNFT = LemurNFT.load(contractAddress, web3j, credentials, DefaultGasProvider())
            val transactionReceipt: TransactionReceipt = nft.mintNFT(walletAddress, tokenUri).send()

            Log.e("Response", transactionReceipt.toString());
            showResponse(transactionReceipt.toString());

        } catch (e: Exception){
            e.printStackTrace();
        }
        return;
    }

    /**
     * Display the response as a toast notification.
     */
    private fun showResponse(response: String){

        val duration  = Toast.LENGTH_LONG;
        val toast = Toast.makeText(applicationContext, response, duration);
        toast.show();

    }

    /**
     * Create a web3j web socket instance from the web socket url.
     */
    private fun createWeb3j(): Web3j {
        val webSocketService = WebSocketService(webSocketUrl, true)
        try {
            webSocketService.connect()
        } catch (e: ConnectException) {
            e.printStackTrace()
        }
        return Web3j.build(webSocketService)
    }

    /***
     * Create credentials from a seed.
     */
    private fun loadCredentials(){
        val masterKeypair = Bip32ECKeyPair.generateKeyPair(MnemonicUtils.generateSeed(seed, ""))
        val path = intArrayOf(44 or HARDENED_BIT, 60 or HARDENED_BIT, HARDENED_BIT, 0, 0)
        val x = Bip32ECKeyPair.deriveKeyPair(masterKeypair, path)
        this.credentials = Credentials.create(x)
    }

}

When you click on the mint button, once you compile and run the application, a toast notification should show up with a transaction receipt.

14. Conclusion

Congratulations, you have been able to create an NFT smart contract and interact with it from an android app.

Building a whive node (Part 2)

Peter Okwara — Wed, 05 Oct 2022 12:23:25 +0000

This tutorial continues from Part 1 which can be found here make sure you go through it before going through this.

Step 8: Generating a whive address

We then need to create an address in which we can use to receive whive tokens. You can do this by running

whive-cli getnewaddress

On the same directory which is whive/src folder. This will output an address that we will use later.

Step 9: Getting cpuminer

Change your directory to the home directory and clone the cpuminer directory.

cd 
git clone https://github.com/cryptozeny/cpuminer-mc-yespower.git

Step 10: Installing the cpuminer dependencies

Some dependencies are needed so that we are able to build the cpuminer. Run the following commands to install the dependencies.

sudo apt-get install build-essential libcurl4-openssl-dev

Step 11: Building cpuminer

Once the dependencies are installed, we can now build by running the command

./build.sh

Step 12: Running cpuminer on your local raspberry pi

Cpuminer can be set up to run on the raspberry pi itself. To do this we run the following command with the address we generated earlier.

./minerd -a yespower -o http://127.0.0.1:1867 -u whive -p pass --no-longpoll --no-getwork --no-stratum  --coinbase-addr=generatedaddress -t 3

Give it some time. You should be able to see some logs indicating that some rewards are coming in.

Step 13: Joining a mining pool

It is also possible to join a mining pool to increase the odds of getting mining rewards. We can do this by running

./minerd -a yespower -o stratum+tcp://34.73.100.13:3333 -u generateaddress.w1 -t 3

Give it some time. Once we have let it run for a line, we can go to the site http://34.73.100.13/workers and check if our generated address shows up.

Conclusion

With this walk through, we were able to

Install raspbian os on the raspberry pi and access it
Install whive dependencies and build it
Run whived
Create a whive address for payment
Install cpuminer dependencies and build it
Run a cpuminer and mine locally
Join a whive mining pool

References

Guide on mining https://whiveio.medium.com/a-guide-on-mining-whive-rewards-with-your-cpu-7e3289e11db7
Running a whive node on a raspberry pi https://peterokwara.hashnode.dev/running-a-whive-node-on-a-raspberry-pi-ck6ix8ssv00k5d9s1m5qoj1fl
Whive pool http://pow.melanin.network/getting_started
Raspberry pi operating system https://www.raspberrypi.org/software/operating-systems/
Raspberry ip ip address https://www.raspberrypi.org/documentation/remote-access/ip-address.md
Ssh access on raspberry pi https://www.raspberrypi.org/documentation/remote-access/ssh/README.md
Raspberry pi installation https://www.raspberrypi.org/documentation/installation/installing-images/README.md
Whive https://github.com/whiveio/whive
Cpuminer-yespower https://github.com/whiveio/cpuminer-mc-yespower

Running a Whive Node (Part 1)

Peter Okwara — Wed, 05 Oct 2022 12:23:10 +0000

Introduction

Whive, is a peer-to-peer blockchain protocol that is incentivizing the building of sustainable energy solutions through Trustless Rewards.

The Protocol was developed by Bithub Africa and a team of global contributors. Bithub Africa is a commercial Blockchain Accelerator that is focused on driving Financial and Energy access across Africa.

The protocol achieves this through a hybrid Proof-of-Work(POW) & Proof-Of-Stake(POS) consensus algorithm that favours devices with CPU(small) processors & are located in regions with a high solar reliability index.

This means by becoming a network participant you shall be able to earn Trustless Rewards that are mined when you run the whive software.

In this tutorial, I will be walking you through on how to set up and run the whive protocol on a Raspberry Pi. You can also run the protocol on a desktop machine or a laptop, unix or linux or windows but with a Raspberry Pi, you get more rewards from it's algorithm.

Prerequisite

The following background knowledge will come in handy

Linux bash shell
Familiarity with Raspberry Pi in general
Components

Components

The following components are needed

Raspberry pi with wifi capability.
SD card with more than 8GB space
Internet access, whether it's through wifi or ethernet cable, if your Raspberry Pi supports WiFi or Ethernet.

Step 1: Installing raspbian operating system

The first step is to download raspbian os and use raspberry pi imager to burn the image on to your sd card. Instructions on how to do that can be found here.

Once the installation is complete, the next step is to be able to access the rasberry pi remotely. One of the best way to do this is via ssh. A ssh file is put in the boot directory, for the headless setup. Instructions on how to do this can be found in step 3. Any of the other steps listed can work, but the headless setup works irregardless to any setup one may have, with or without a screen.

Once that is done, the remaining step is to identify your IP address so that you can be able to access your raspberry pi remotely. A guide on how to get your raspberry pi address can be found here. I normally use fing to identify the IP address of my raspberry pi.

You can now access your raspberry pi using the steps shown in step 4 with the username as pi and password as raspberry.

Step 2: Getting whive

Once you have access to your raspberry pi terminal, go to the home directory by typing

cd

Ensure you have git installed. You can install git by running

sudo apt-get install git

And clone the whive repository by running

git clone https://github.com/whiveio/whive.git

Step 3: Installing whive dependencies

Before one is able to build whive, you need to install the dependencies. You can do this by running.

sudo apt-get install -y build-essential libtool autotools-dev automake pkg-config bsdmainutils python3

Once the previous step is done, you can then run

sudo apt-get install -y libssl-dev libevent-dev libboost-system-dev libboost-filesystem-dev libboost-chrono-dev libboost-test-dev libboost-thread-dev

The ppa for bitcoin does not exist for raspbian os. But we can still add it. To do this we edit the /etc/apt/sources.list

sudo nano /etc/apt/sources.list

And add the following lines to the file

deb http://ppa.launchpad.net/bitcoin/bitcoin/ubuntu cosmic main 
deb-src http://ppa.launchpad.net/bitcoin/bitcoin/ubuntu cosmic main

You can then do Ctrl + O to save and Ctrl + X to exit. Once this is done you can then add the key by running the command:

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys C70EF1F0305A1ADB9986DBD8D46F45428842CE5E

And update by running

sudo apt-get update

With this we can now install the remaining dependencies, especially Berkely Db by running

sudo apt-get install software-properties-common

sudo add-apt-repository ppa:bitcoin/bitcoin

sudo apt-get update

sudo apt-get install -y libdb4.8-dev libdb4.8++-dev

Step 4: Building whive

Enter the whive directory you just cloned by running

cd whive

And then build whive by running

./autogen.sh
./configure
make

Step 5: Configuring whive

Go to the home directory by typing

cd

Make a new folder called .whive and create a new file called whive.conf within the folder

mkdir .whive
cd .whive
nano whive.conf

Copy and paste the following settings within the nano editor.

server=1
daemon=1
listen=1
txindex=1
rpcuser=whive
rpcpassword=pass

You can now save this settings by running Ctrl + O to save and Ctrl + X to exit.

Step 6: Running whive

Once whive has finished building, you can now move to the src folder within the whive folder

cd
cd whive/src

And then run

whived -daemon

Step 6: Check if whive is running

To check if whive is running, within the same whive/src folder, run

whive-cli getblockchaininfo

You can also run

htop

And check to see if there is whived in the running processes.

Step 7: Generating a whive address

We then need to create an address in which we can use to receive whive tokens. You can do this by running

whive-cli getnewaddress

On the same directory which is whive/src folder. This will output an address that we will use later.

To continue with the tutorial, please check out Part 2

Pay for light (Part 2)

Peter Okwara — Thu, 17 Sep 2020 08:13:00 +0000

This tutorial continues from Part 1 which can be found here make sure you go through it before going through this.

Step 7: Api Setup

The code for the api can be found here. All is needed is to download the folder and run npm run install within the folder. In the following sections we will walk through the major files within the api.

Step 8: TextHelper

The TextHelper class holds helper functions to help store information on the Tangle.

/**
 * Helper functions for use with text.
 */
export class TextHelper {
}

The encodeNonASCII function encodes non ASCII characters to escaped characters.

/**
     * Encode Non ASCII characters to escaped characters.
     * @param value The value to encode.
     * @returns The encoded value.
     */
    public static encodeNonASCII(value: string): string | undefined {
        return typeof (value) === "string" ?
            value.replace(/[\u007F-\uFFFF]/g, chr => `\\u${(`0000${chr.charCodeAt(0).toString(16)}`).substr(-4)}`)
            : undefined;
    }

The decodeNonASCII function decodes escaped characters to non ASCII characters.

/**
     * Decode escaped Non ASCII characters.
     * @param value The value to decode.
     * @returns The decoded value.
     */
    public static decodeNonASCII(value: string): string | undefined {
        return typeof (value) === "string" ?
            value.replace(/\\u([\d\w]{4})/gi, (match, grp) => String.fromCharCode(parseInt(grp, 16))) :
            undefined;
    }

Step 9: TrytesHelper

The necessary functions were imported to the TrytesHelper class. This will help convert objects to trytes and trytes to objects. In case we need to generate a hash, we also create a function to generate a given hash.

import { asciiToTrytes, TRYTE_ALPHABET, trytesToAscii } from "@iota/converter";
import * as crypto from "crypto";
import { TextHelper } from "./textHelper";

The create class helps with all the trytes operations we will deal with.

/**
 * Helper functions for use with trytes.
 */
export class TrytesHelper {

}

The toTrytes function converts an object to trytes.

/**
     * Convert an object to Trytes.
     * @param obj The obj to encode.
     * @returns The encoded trytes value.
     */
    public static toTrytes(obj: unknown): string {
        const json = JSON.stringify(obj);
        const encoded = TextHelper.encodeNonASCII(json);
        return encoded ? asciiToTrytes(encoded) : "";
    }

The fromTrytes function converts trytes to a given object.

/**
     * Convert an object from Trytes.
     * @param trytes The trytes to decode.
     * @returns The decoded object.
     */
    public static fromTrytes<T>(trytes: string): T {
        if (typeof (trytes) !== "string") {
            throw new Error("fromTrytes can only convert strings");
        }

        // Trim trailing 9s
        const trimmed = trytes.replace(/\9+$/, "");

        if (trimmed.length === 0) {
            throw new Error("fromTrytes trytes does not contain any data");
        }

        const ascii = trytesToAscii(trimmed);
        const json = TextHelper.decodeNonASCII(ascii);
        return json ? JSON.parse(json) : undefined;
    }

The generateHash function generates a random hash for the length provided.

  /**
     * Generate a random hash.
     * @param length The length of the hash.
     * @returns The hash.
     */
    public static generateHash(length: number = 81): string {
        let hash = "";

        while (hash.length < length) {
            const byte = crypto.randomBytes(1);
            if (byte[0] < 243) {
                hash += TRYTE_ALPHABET.charAt(byte[0] % 27);
            }
        }

        return hash;
    }

Step 10: MQTT

The necessary files were imported using the code below. One is the Mqtt library. The other is the configuration files.

import mqtt from "mqtt";
import config from "../data/config.local.json";

The MqttHelper class handles all the Mqtt functions.

/**
 * Class to handle Mqtt functions
 */
export class MqttHelper {
}

Inside the class, variables were set which represent the configuration files for the Mqtt connection to Adafruit IO, which acts like our broker in the cloud. This was done using the code below.

/**
     * The mqtt client
     */
    protected _mqttClient: mqtt.MqttClient;

    /**
     * The mqtt host
     */
    protected readonly _host: string;

    /**
     * The username for the mqtt host/broker
     */
    protected readonly _username: string;

    /**
     * The password for the mqtt host/broker
     */
    protected readonly _password: string;

    /**
     * The feed/topic to subscribe to
     */
    protected readonly _feed: string;

    /**
     * The port to use when connecting to the mqtt host/broker
     */
    protected readonly _port: number;

In our constructor, we set up our variables to the values we stored in our configuration files.

constructor() {
        this._mqttClient = null;
        this._host = `mqtts://${config.MQTT_CONFIG.ADAFRUIT_IO_URL}`;
        this._username = config.MQTT_CONFIG.ADAFRUIT_USERNAME;
        this._password = config.MQTT_CONFIG.ADAFRUIT_IO_KEY;
        this._feed = `${config.MQTT_CONFIG.ADAFRUIT_USERNAME}/f/${config.MQTT_CONFIG.ADAFRUIT_IO_FEEDNAME}`;
        this._port = config.MQTT_CONFIG.ADAFRUIT_IO_PORT;
    }

We then created a function that will help us connect to our broker. In this case Adafruit IO .

 /**
   * Function to connect to a mqtt host/broker and subscribe to events coming from it
   */
public connect(): void {

}

Connect to the cloud broker with username, password and port to use.

// Connect mqtt with credentials (in case of needed, otherwise we can omit 2nd param)
        this._mqttClient = mqtt.connect(
            this._host, { username: this._username, password: this._password, port: this._port });

In case of error we want to log the error and break off the connection.

 // Mqtt error calback
        this._mqttClient.on("error", err => {
            console.log(err);
            this._mqttClient.end();
        });

In case we successfully connect, we print out a message that our computer has successfully connected.

// Connection callback
        this._mqttClient.on("connect", () => {
            console.log(`mqtt client connected`);
        });

We specify the feed we want to connect to and subscribe to it.

// mqtt subscriptions
        this._mqttClient.subscribe(this._feed);

In case we get a message, we will just show the message we received.

  // When a message arrives, console.log it
        this._mqttClient.on("message", message => {
            console.log(message.toString());
        });

On close, we will just close the Mqtt client.

this._mqttClient.on("close", () => {
            console.log(`mqtt client disconnected`);
        });

We created another function for publishing messages to Mqtt.

 /**
     * Function  to send messages to the mqtt client/broker
     * @param message The message to be sent
     */
    public sendMessage(message: string | Buffer): void {
        this._mqttClient.publish(this._feed, message);
    }

Step 11: MAM

We import the necessary libraries.

import { composeAPI } from "@iota/core";
import { createChannel, createMessage, mamAttach } from "@iota/mam.js";
import fs from "fs";
import config from "../data/config.local.json";
import { INodeConfiguration } from "../models/configuration/INodeConfiguration";
import { TrytesHelper } from "./trytesHelper";

A class called MamHelper was created which will helps us with our connection to the Mam channel.

export class MamHelper {
}

In it we import the configuration settings for the node we want to use.

/**
  * Node configuratin settins
  */
  private readonly _nodeConfig: INodeConfiguration;

  constructor() {
       this._nodeConfig = config.node;
   }

We created a function to store messages on the mam channel.

/**
 * Function to store information on the mam channel
 * @param asciiMessage The message to be stored on the mam channel
 */
public async create(asciiMessage: object): Promise<void> {
}

We then created a try-catch to catch errors if the whole process of storing the messages in the mam channel fails.

try {

} catch (error) {
            throw new Error(`Could not store the message on the mam channel ${error} `);
}

We then try to load the channel state and parse it.

 let channelState;

            // Try and load the channel state from json file
            try {
                const currentState = fs.readFileSync("./channelState.json");
                if (currentState) {
                    channelState = JSON.parse(currentState.toString());
                }
            } catch (e) { }

If we are unable to load the channel state, we create a new one.

// If we couldn't load the details then create a new channel.
if (!channelState) {

    // set up details for the channel
    const mode = "public";

    // create a new mam channel
    channelState = createChannel(TrytesHelper.generateHash(81), 2, mode);
}

We create a Mam message using the channel state

// Create a MAM message using the channel state.
const mamMessage = createMessage(channelState, TrytesHelper.toTrytes(asciiMessage));

Then display mam channel information

// Display the details for the MAM message.
console.log("Seed:", channelState.seed);
console.log("Address:", mamMessage.address);
console.log("Root:", mamMessage.root);
console.log("NextRoot:", channelState.nextRoot);

Setup node configuration for the provider.

 const iota = composeAPI({
          provider: this._nodeConfig.provider
 });

Then attach the message to the mam channel.

// Attach the message.
console.log("Attaching to tangle, please wait...");

await mamAttach(iota, mamMessage, this._nodeConfig.depth, this._nodeConfig.mwm);

We provide a link where we can see all the information from the Mam channel.

console.log(`You can view the mam channel here https://utils.iota.org/mam/${mamMessage.root}/devnet`);

We then store the state of the Mam channel json file

 // Store the channel state.
 try {
         fs.writeFileSync("./channelState.json", JSON.stringify(channelState, undefined, "\t"));
 } catch (e) {
         console.error(e);
 }

Step 12: Iota-Pay

We import the necessary libraries and files for the project.

import bodyParser from "body-parser";
import express from "express";
import paymentModule from "iota-payment";
import scheduler from "node-schedule";
import { MamHelper } from "./utils/mamHelper";
import { MqttHelper } from "./utils/mqttHelper";

We then set up an express server.

const app = express();

app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: true }));

We import the MqttHelper function. We then connect and first of all turn the relay off by sending an "OFF" message.

const mqttClient = new MqttHelper();
mqttClient.connect();
mqttClient.sendMessage("OFF");

We then set up our options for the payment module. This involves enabling the api option, the dashboard option and the web socket option.

const options = {
    api: true,
    dashboard: true,
    websockets: true
};

Set up an express server and run it. This provides us with two routes. The /iotapay route and the /iotapay/api route.

const server = paymentModule.createServer(app, options);

// Start server with iota-payment dashboard on '/iotapay' and api on '/iotapay/api'
server.listen(5000, () => {
    console.log(`Server started on http://localhost:5000 `);
    console.info(`Please visit http://localhost:5000/iotapay in your browser`);
});

Set up a time variable that will return the current date and time.

const time = () => {
    return new Date();
};

We then create a payment handler. The payment handler will be called once a payment is successful.

//Create an event handler which is called, when a payment was successful
const onPaymentSuccess = async payment => {
}

We store all the payment information into variable. This also includes the payment event itself.

const transaction = {
        paid: payment.paid,
        type: payment.type,
        value: payment.value,
        address: payment.address,
        index: payment.index,
        id: payment.id,
        txInfo: {
            timestamp: payment.txInfo.timestamp,
            hash: payment.txInfo.hash,
            value: payment.txInfo.value,
            message: payment.txInfo.message
        },
        event: [`User has paid ${payment.txInfo.value} tokens for lights`]
    };

Set up the mam channel and create a message.

const mamHelper = new MamHelper();

await mamHelper.create(transaction);

We then wait for 3 seconds before adding the time we turn the lights on and push the whole transaction to the mam channel.

setTimeout(async () => {
        // send the event that the lights are now on
        transaction.event.push(`Lights are on ${time()}`);
        await mamHelper.create(transaction);

        // tslint:disable-next-line: align
    }, 3000);

Let's make the amount of time (in minutes) the lights will be on be the amount of IOTA tokens multiplied by 60000.

 const seconds: number = payment.txInfo.value * 60000;

Let's set up the start time and the end time, the lights will be on.

 const startTime = new Date(Date.now());
 const endTime = new Date(startTime.getTime() + seconds);

To keep the lights on, we send a Mqtt message every 10 seconds for the amount of time we have set.

await scheduler.scheduleJob({ start: startTime, end: endTime, rule: `*/10 * * * * *` }, () => {
        mqttClient.sendMessage("ON");
        console.log("😊");
   });

Once the time is over, we set the end time for which which the off message will be sent.

 const newEndTime = new Date(endTime.getTime() + 30000);

We send an OFF mesage for another 10 seconds for a period of 30 seconds to ensure the relay is off.

await scheduler.scheduleJob({ start: endTime, end: newEndTime, rule: `*/10 * * * * *` }, () => {
        mqttClient.sendMessage("OFF");
        console.log("😐");
    });

We then immediately send that the lights are off to the mam channel.

await scheduler.scheduleJob({ start: endTime, end: newEndTime, rule: `*/30 * * * * *` }, async () => {

        // send the event that the lights are now off
        transaction.event.push(`Lights are off ${time()}`);
        await mamHelper.create(transaction);
    });

At the end of this, we now call the function onPaymentSuccess that we just created.

paymentModule.onEvent("paymentSuccess", onPaymentSuccess);

Step 13: Configuration

There are two configurations we need to set up. One is for the MQTT and the IOTA Node, to store transaction information using MAM. The other one is a seed for generating an address for payment and connecting to the IOTA Nodes only to do payments.

Same with the configuration on step 4, we would only need to change the adafruit io username and adafruit io key. This configuration is found here. The file should be saved as config.local.json.

{
    "MQTT_CONFIG": {
        "ADAFRUIT_IO_URL": "io.adafruit.com",
        "ADAFRUIT_USERNAME": "",
        "ADAFRUIT_IO_KEY": "",
        "ADAFRUIT_IO_FEEDNAME": "pay-for-light.bulb-relay",
        "ADAFRUIT_IO_PORT": 8883
    },
    "node": {
        "provider": "https://nodes.devnet.iota.org:443",
        "depth": 3,
        "mwm": 9
    }
}

Create another file called a .env file in the api folder. Add the following configuration.

seed=
iotaNodes=["https://nodes.comnet.thetangle.org:443"]

Generate a seed by heading over to https://docs.iota.org/docs/getting-started/0.1/tutorials/create-a-seed and running one of the commands to generate a seed. After that you can paste the seed as it is in the seed= parameter.

Step 14: Testing

We can now run the api server by running the command below.

cd api && npm run start

This boots up the api server as shown below.

Note: Running npm run start-dev puts its in a loop. Don't use it.

Once the api server has boot up, you can now go to the storefront to get your IOTA address. This is highlighted in red in the above image as.

http://localhost:5000/iotapay/#/

Once you go to the url on your machine or server, the page looks like this.

Clicking on Show QR Code displays the QR code. The QR code can be scanned to get the IOTA address to make payments to.

Clicking on Copy address copies the IOTA address to the clipboard. Once we have the IOTA address, we can now make payments to the given address.

Go to the IOTA Comnet *Fauchet*site here. The site provides free tokens for the community testent. The tokens will be used to simulate a payment process.

Enter the address to send tokens on the IOTA Comnet address to and specify the amount.

For now we will send 3 IOTA tokens. Once we enter the amount, we can now hit send. One can also add an optional message to accompany the payment.

Once the payment is successfull, a message will pop up, Transaction sent: with a link to the transaction on the tangle. This also shows up on the console as Payment Successful! Address XXXXX

Going to the link shown above (You can view the mam channel here), we can see the in the mam explorer, the payment information and the events. This is shown in the photos below.

The event are:

User has paid 3 tokens for lights
Lights are on
Lights are off

The lights will then turn on and then turn off after 3 minutes.

Limitations

Limitations of the project are:

Security has not been implemented in the MAM channel for this project. At the moment, anyone can access the information. Security can be enhanced by using private mode or restricted mode.
There is no mechanism for handling multiple payments at the same time. One can only do one payment at a time for it to work correctly. Probably having a deposit account and checking the amount would help. Or queue the payments
Maximum amount of time the lights can be turned on is 59 minutes. This limitation is easy to fix, it just involves modifying the *npm *module, node schedule to allow for more date and time.
One cannot get a specific transaction. It shows the compete list of transactions from which one has to manually search for a specific transaction.

References

Some of the references for this code is found here:

The payment module https://github.com/iota-pay/iota-payment-module
Masked Authenticated Messaging (MAM) https://github.com/iotaledger/mam.js
Connecting to Adafruit IO https://github.com/adafruit/adafruit-io-node
Building management system https://github.com/peterokwara/BuildingManagement
Energy boss must wake up Kenya Power https://www.businessdailyafrica.com/analysis/columnists/Energy-boss-must-wake-up-Kenya-Power/4259356-5618224-cm7w40z/index.html

Pay for Light (Part 1)

Peter Okwara — Wed, 16 Sep 2020 19:23:44 +0000

Introduction

Kenya Power, our local power distributer, owns Kenya Electricity Generating Company, 218 million dollars despite being a monopoly in the country. The fast declining revenues has been attributed to theft facilitated by it’s own employees and it’s own legacy structure.

Innovative technologies such as smart grids, smart meters combined with technologies such as Distributed Ledger technologies and Internet of Things to curb the massive theft.

In this tutorial we will be using two technologies Distributed Ledger Technology and Internet of Things to turn on lights for a period of time. This will be based on how much money we will be sending to our account. IOTA tokens will represent the amount of money we will be sending to our account. All transactions will be recorded on the Tangle. Hopefully with this level of traceability, it will be harder for actors to steal information from electricity distribution systems.

Some of the benefits of Distributed Ledger Technology, to be specific IOTA and IoT in the energy sector are

Transparency, make supply chains more transparent, leading to real price for value and linking milestones to actions.
Trust, enable creation of marketplaces for sourcing in an ecosystem.
Efficiency, lower cost of compliance and lower cost of reconciliation (between subsidiaries).
Control and security, where auditing, cost, control and accounting will be impacted as the handling of payments can be streamlined and automated.
Zero transaction fees.
Can handle micro-transactions (very small amount of money).
Can be used with very basic sensors.
Quick confirmation time.
Highly secure from attacks.

Requirements

The following background knowledge will come in handy

Node js.
Javascript.
Typescript.
Python.
Some knowledge on IOTA Blockchain or Blockchains in general, Electronics and Mqtt.

This tutorial does not cover the basic concepts of Mqtt, Mam or IOTA Payments. You can learn more about this technologies here.

Hardware Requirements

The components required are:

ESP 8266-01 https://ktechnics.com/shop/wireless-devices/rfidnfc/esp8266-esp-01-serial-wifi/
LM1117T Transistor https://ktechnics.com/shop/intergrated-circuits/voltage-regulators-ics/lm1117t-lm1117-low-dropout-voltage-regulator-3-3v/
10uF Capacitor https://store.nerokas.co.ke/index.php?route=product/product&path=81_117&product_id=961
Switch https://store.nerokas.co.ke/index.php?route=product/product&product_id=1995&search=switch&page=3
10k Ohm Resistor (quantity 2) https://store.nerokas.co.ke/index.php?route=product/product&product_id=1675&search=resistor+10&description=true
Breadboard https://ktechnics.com/shop/prototyping/breadboard-mb102-solderless-type-830-points/
Green Led https://ktechnics.com/shop/components/capacitors/light-emitting-diode-led-green/
5V Power Supply
470 Ohm Resistor https://store.nerokas.co.ke/index.php?route=product/product&product_id=451&search=470+&description=true
5v 1 Channel Relay https://store.nerokas.co.ke/index.php?route=product/product&product_id=1679&search=switch&description=true
Male to Male wires https://store.nerokas.co.ke/index.php?route=product/product&product_id=120&search=male+to+male&description=true
Male to Female wires
Bulb https://www.jumia.co.ke/lotus-enhanced-led-9w-b22-warm-white-bulb-757050.html
Bulb holder https://sky.garden/product/PnsY7J3N
Usb programmer https://www.aliexpress.com/item/32985707091.html?spm=a2g0o.productlist.0.0.275a759bLItMFS&algo_pvid=0eb05015-3a2d-46d4-83ee-049fbf63e31e&algo_expid=0eb05015-3a2d-46d4-83ee-049fbf63e31e-0&btsid=0ab50f0815982177184654489e2b0e&ws_ab_test=searchweb0_0,searchweb201602_,searchweb201603_

PS: You can probably get all these components, half the price at Aliexpress .

Warning Use proper care when handling large current.

Step 1: Circuit set up

The first step is to build up the circuit. The designs were done with both EagleCad and Fritzing and also for EagleCad.

Set up the circuit as shown in the figure below. You can open the following image by downloading fritzing and opening the fritzing file in the url https://github.com/peterokwara/pay-for-light/tree/master/schematics/Fritzing

You can also use EagleCad to open the circuit. To do this, you can open the Board and Schematics file after you get them from here

The EagleCad design can also be etched on to a photochromatic board. The final look of the board after it has been etched on a board based on the board when disconnected.

When connected to a bulb and power supply.

NB: The project can still be done on a breadboard. It's not a must for one to etch it on a board.

Step 2: Adafruit IO

Adafruit IO is a cloud service where one can connect IoT devices to send and receive data from it. It acts like a broker in the cloud.
Create an account by going to https://io.adafruit.com/ and click on sign up. One you have signed up or you have already have an account you can now sign in.

Once we are able to login, go to the Feeds tab an click on View all Feeds as highlighted below.

The first thing we would like to do is to create a group under which we will put our feed. On Actions, we click on Create a new group.

Call the new group pay-for-light and click Create.

Create a new feed by clicking on Actions and select Create a New Feed.

For the new feed, we will call it as bulb-relay. We will add it to the group we just created. The group being pay-for-light. Once we do this we can now click Create.

We can now go back to the feed and get our Adafruit IO Key. We click on the Adafruit IO Key.

Under username, we see our Active Key. This is the key we will use to connect to our Adafruit IO account to post the mqtt information.

Step 3: Wi-Fi set up

Use the code shown below to set up Wi-Fi. What it does is that it takes in the WIFI_ESSID and WIFI_PASSWORD and tries to connect to your Wi-Fi network. If it successfully connects, it prints out Connection successful and the network information. If it is already connected, it will print Already connected.

def connect(): 
""" Connects to a wifi hotspot.  Takes in the wifi username and the wifi password from a config.py file and  tries to connect to the wifi username defined.  

Args:     
    None.  
Returns:     
    A print statement that states whether the *nodemcu* model is connected      
    to a wifi network, already connected to a wifi network and the network      
    details. 
"""  

import network 
import config  

ssid = config.WIFI_CONFIG['WIFI_ESSID'] 
password = config.WIFI_CONFIG['WIFI_PASSWORD'] 
station = network.WLAN(network.STA_IF)  

if station.isconnected() == True:     
    print("Already connected")  

station.active(True) 
station.connect(ssid, password)  

while station.isconnected() == False:     
    pass  

print("Connection successful") 
print(station.ifconfig())

Create a config file that the code will use to fetch the username and password, and use it to connect to the Wi-Fi. Ensure you enter your Wi-Fi name and password to the config file to connect to.

MQTT_CONFIG = {     
    'SENSOR_ID': '',     
    'MQTT_HOST': '',     
    'PORT': '',     
    'PUB_TOPIC': '' 
}  
WIFI_CONFIG = {     
    'WIFI_ESSID': '',     
    'WIFI_PASSWORD': '' 
}

Setup the main code to look like this. It's main purpose is to connect to the wifi network we specified in the configuration file.

import wifiSetup     

# Connect to wifi hotspot 
wifiSetup.connect()

Step 4: Configuration Setup

Set up the config file with the following default values. Assuming we followed all the settings for Adafruit IO we used when setting up, we would have the following default values below. The only values we would need to replace are the wifi configurations, the adafruit io username and adafruit io key.

WIFI_CONFIG = {
    'WIFI_ESSID': '',
    'WIFI_PASSWORD': ''
}

MQTT_CONFIG = {
    'ADAFRUIT_IO_URL': 'io.adafruit.com',
    'ADAFRUIT_USERNAME': '',
    'ADAFRUIT_IO_KEY': '',
    'ADAFRUIT_IO_FEEDNAME': 'pay-for-light.bulb-relay'
}

Step 5: Relay

Import the following files. This includes the Mqtt libraries, config libraries, wifi connection file among others.

import os
from umqtt.simple import MQTTClient
import connectWifi
import time
import config
import json
import sys
import machine
from machine import Pin

Next step is to connect to wifi. Call the function the function connect from the connectWifi python file.

# connect to wifi
connectWifi.connect()

Set up the GPIO pin we will use to turn on or off the pin. We want to use GPIO_2 for this.

# set GPIO_2 pin as an output pin
RPin = Pin(2, Pin.OUT, value=0)

Manually generate a client id for Mqtt.

# generate a client id
random_num = int.from_bytes(os.urandom(3), 'little')
mqtt_client_id = bytes('client_'+str(random_num), 'utf-8')

The next step is to connect to the Adafruit IO Service in the cloud.

# import configuration setup
ADAFRUIT_IO_URL = config.MQTT_CONFIG["ADAFRUIT_IO_URL"]
ADAFRUIT_USERNAME = config.MQTT_CONFIG["ADAFRUIT_USERNAME"]
ADAFRUIT_IO_KEY = config.MQTT_CONFIG["ADAFRUIT_IO_KEY"]
ADAFRUIT_IO_FEEDNAME = config.MQTT_CONFIG["ADAFRUIT_IO_FEEDNAME"]

We then set up a function to turn the relay on.

def relay_on():

    # Sends a message to the broker that the relay has been turned on, and then turns on the relay.
    send("Relay on")
    RPin.on()

And a function to run off the relay.

def relay_off():

    # Sends a message to the broker that the relay has been turned off, and then turns off the relay.
    send("Relay off")
    RPin.off()

Set up a function to send a message to the broker. The broker in this case is the Adafruit IO service in the cloud. This takes in the feed and the data we need to send to our Mqtt service.

def send(data):

    # Sends a message to the broker.
    client.publish(mqtt_feedname, json.dumps(data))

We then subscribe to messages we will receive from our Mqtt service in the cloud which is Adafruit IO. If the message is on, we call the function to turn on the relay. If the message is off, we want to turn off the relay.

def cb(topic, msg):

    # Callback which is called when subscribed data is received.
    print('Received Data:  Topic = {}, Msg = {}'.format(topic, msg))
    command = msg.decode('ASCII')
    if command == "ON":
        relay_on()
    elif command == "OFF":
        relay_off()

On to the main method. We first try to connect to our Mqtt Server. If this fails we, print that we are not able to connect to the Mqtt server. We then sleep for 10 minutes and reset the microcontroller.

def main():

    # Connect to a mqtt server
    try:
        client.connect()
    except Exception as e:
        print('could not connect to MQTT server {}{}'.format(type(e).__name__, e))
        time.sleep(10)
        machine.reset()

We then call the callback function and set it up within the main function.

# set the callback
client.set_callback(cb)

We call the subscribe function and the feed we want to subscribe to and send a test message.

# subscribe to a given feed name
client.subscribe(mqtt_feedname)

# send test message
send("Is this... now?")

Then we want to check for incoming messages or commands. This command runs infinitely. In case we get any errors, we send over, we print an error message, sleep for 10 seconds then reset the microcontroller.

# check for incoming messages/commands
while True:
    try:
        if True:
            # Blocking wait for message
            client.wait_msg()
        else:
            # Non-blocking wait for message
            client.check_msg()
            # Then need to sleep to avoid 100% CPU usage (in a real
            # app other useful actions would be performed instead)
            time.sleep(1)
    except OSError as e:
        print('Failed to connect to MQTT broker. Reconnecting...')
        time.sleep(10)
        machine.reset()

Step 6: Push files

You need to have micropython running on the esp for it to work, I normally use esptool to upload the firmware on to the esp.

Plug in the esp8266-01 on to an esp programmer as shown below and plug it in to your computer.

Identify the port in which the programmer is connected to. You can do this by going to the device manager. In this case it's COM4.

The next step was to download the firmware. The firmware is available from here. Once the firmware was downloaded, I opened the Nodemcu software and set up the Serial port and the firmware. Baud rate was set to 115200 and flash mode set to Dual I/O.

The next step was to press the flash switch on the esp programmer and click on the Flash NodeMCU button on the NodeMCU PyFlasher software. The image below shows what happens when you successfully flash the firmware on to the esp.

For UNIX users, an alternative way of setting up is using the terminal. This requires you know the location of the downloaded firmware and the port the NodeMCU is connected to. This is:

sudo apt install python-pip
sudo pip install esptool

Erasing the flash

sudo esptool --port /dev/ttyUSB0 erase_flash

Uploading the flash to the device

sudo esptool.py --port /dev/ttyUSB0 --baud 115200 write_flash --flash_size=detect 0 ~/Downloads/esp8266-20171101-v1.9.3.bin

To test if the board is working well, we will try to access the board and turn on the on board LED. To do this on Windows we need to use putty. After installing putty, the next step is setting up the board connection. WE ensure the serial line is COM4, the port the esp programmer is connected to, the speed set to 115200 and the connection type set to serial.

The command I normally run is

sudo esptool.py --port /dev/ttyUSB0 --baud 115200 write_flash --flash_size=detect 0 ~/Downloads/esp8266-20171101-v1.9.3.bin

I wrote the following code to see if the board is working or not. The on board led should turn on and off based on whether pin.on() or pin.off() has been toggled.

To store the python files on the nodemcu, I normally use ampy. Installing it on a windows environment, assuming you have python installed, you run:

pip install adafruit-ampy

Or if you are using Linux or Mac OSX you run:

sudo pip3 install adafruit-ampy

To list the files, remove files or put files on to the NodeMCU, you run:

sudo ampy --port /dev/ttyS4 --baud 115200 ls
sudo ampy --port /dev/ttyS4 --baud 115200 rm <filename>
sudo ampy --port /dev/ttyS4 --baud 115200 put <filename>

To put the 3 files we just created, you run:

sudo ampy --port /dev/ttyS4 --baud 115200 put main.py
sudo ampy --port /dev/ttyS4 --baud 115200 put config.py
sudo ampy --port /dev/ttyS4 --baud 115200 put wifiSetup.py

This all assumes that the port /dev/tty4 you used is the correct one for your machine. Check device manager to know which port your device is connected to.

You can use a Wi-Fi scanner to check if your device is connected. I used Fingbox to check if the NodeMCU is connected to the Wi-Fi network.

To continue with the tutorial, please check out Part 2 here