# Getting started The following tutorial is a hello world equivalent of using tools provided by [Thy Street](https://thystreet.com). ![](https://3941591838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfxR1BFQq6fVoNHpxrr%2Fuploads%2Fgit-blob-cc35da0576927ebbaba5669ddd5f990709dfcdf3%2Fimage.png?alt=media) {% embed url="" %} ## About Device: For keeping it simple, the setup that we will be using is following: * **Hardware:** ESP32 devkit v1 module. * **Software**: Arduino using platform.io * **MQTT:** Any MQTT server available public {% hint style="info" %} This guide majorly focuses on how you can set up a simple workflow for your device using Thy Street APIs. If you are interested in how to set up your environment, please check out Platform.io[ official documentation.](https://docs.platformio.org/en/latest/frameworks/arduino.html) {% endhint %} After a simple google search, we found [HiveMQ](https://www.hivemq.com/mqtt-cloud-broker/) provides a free MQTT broker in their basic plan.Set up your details and get your MQTT credentials. We will be using the following details for the rest of this tutorial: * **Username:** USER\_ID * **Password:** DEVICE\_PASSWORD * **Hostname:** example.hivemq.cloud {% hint style="info" %} Please understand we are in no way associated with HiveMQ., and this is not any sponsored post. The decision to select HiveMQ was purely random. {% endhint %} {% hint style="info" %} You can download the stater code from [github](https://github.com/thystreet/esp32-blink-example). Starter code is in `starter` branch. {% endhint %} ## Dashboard Actions * Login into the dashboard. * [Enable payment](/accounts/payment) (it takes up to 48 business hours to create your account in the payment gateway.) * [Add a new device](/devices/create-device). * [Create a tariff card](/tariff-manager/edittariff) with below details: * **Currency:** INR * Add an entry in the tariff card with the following details: * **Name:** blink * **Title:** Fresh LED blinks * **Minimum Value:** 0 * **Maximum Value:** 10 * **Increment:** 1 * **Price:** 10 * **Tax1** rate in percentage **8** * Create a [custom adapter](/devices/webhook/custom-adapter) to convert our HTTP webhook data to MQTT Arduino data, use the MQTT credentials created above. ## Client Integration * Get the [API credentials](/accounts/account-settings/api-credentials) from your account page. * Add [Thy Street client SDK](https://platformio.org/lib/show/12370/thystreet/installation) in your platform io project. #### Add authentication. ```cpp #include "DeviceApi.h" ... const char *apiKey = "Thy Street API Key"; const char *apiSecret = "Thy Street API secret"; Tiny::DeviceApi api; void setup() { ... api.setAuthorization(apiKey, apiSecret); ... } ``` #### Generate new token and set device status to available ```cpp void setup() { ... auto tokenResponse = api.generateToken(); Serial.println(resp.obj.c_str()); Tiny::DeviceStatusDto dto; dto.setAvailable(true); dto.setDeviceId("device-id"); auto resp = api.setStatus(dto); Serial.println(resp.code); Serial.println(resp.obj.c_str()); ... } ``` #### Update your MQTT listener loop ```cpp // Mark the order status as confirmed // Blink the LED 8 times // Generate the token again for the next customer // Mark order status as completed. ``` As a last step, make the device public. (This is a paid action and will ask for a [subscription](https://thystreet.com/pricing)). Upload the code on your esp32 and start the device. Navigate to the device's page, select 3 led blinks, click on pay. Once you enter the code and make the payment, the onboard led should blink three times. {% hint style="info" %} Help your customers by adding [FAQs](/frequently-asked-questions/what-are-faqs), and support information for your device. {% endhint %} Download and print the device's QR code, install your device and enjoy your sales on the [payment gateway's dashboard](https://dashboard.razorpay.com). {% hint style="info" %} When sharing your device installation over social media, please don't forget to tag us. If you have a device idea feel free to discuss with the [community](https://github.com/thystreet/thystreet/discussions/categories/ideas) {% endhint %} # What is a device? ## **What are IoT devices?** IoT devices are nonstandard computing devices that connect wirelessly to a network and have the ability to transmit data, such as the many devices on the internet of things. IoT involves extending internet connectivity beyond standard devices, such as desktops, lapttops, smartphones, and tablets, to any range of traditionally dumb or internet-enabled physical devices and everyday objects. You can communicate and interact with them over the internet. [Learn more](https://internetofthingsagenda.techtarget.com/definition/IoT-device) #### Device examples with Thy Street api {% content-ref url="/pages/-MgB6gYgPeznJAXNifKC" %} [Liquid Vending Device](/examples/liquid-vending-device) {% endcontent-ref %} # Create Device ## Prerequisites Before you begin, get access to the [Thy Street Dashboard](https://thystreet.com/dashboard) by creating an [account](https://thystreet.com/register). ## Create New Device 1. Login into the [Thy Street Dashboard](https://thystreet.com/dashboard) and navigate to the [Devices](https://thystreet.com/devices) page. 2. Click on the **New Device** button. 3. In the **Add Device** pop-up page 1. Enter your **Device name,** this is the name displayed on your device's public URL. 2. Describe the device in **Description.** This information will be displayed on your device's public URL and will help the user understand the overview of all the paid actions this device will perform. 4. Click on **Add Device** to create a new device. {% hint style="info" %} #### Next Steps Now that your device is created, learn about how you can [enable payment](/accounts/payment), manage your device's paid actions using our [tariff manager](/devices/what-is-a-device). {% endhint %} # Device Page There are different ways in which you can configure your device. They are mainly divided between: ## **General** You update the following details: * **Name** of your device * **Summary** for your device * Make your device **Public,** you need to have a subscription to make the device public, learn more about our [pricing](https://thystreet.com/pricing). * **Open/Close** device for service \*\*\*\* Access of the device can be changed using the two | Public/Private | Open/Close for service | Owner Access | Customer Access | | -------------- | ---------------------- | ------------------------------ | ------------------------------ | | Public | Open | Available | Available | | Public | Close | Available with tariff disabled | Available with tariff disabled | | Private | Open | Available | Unavailable | | Private | Close | Unavailable | Unavailable | ## **Details** Add additional details to your device's profile ### Set Integration details {% hint style="info" %} Learn more about webhook by visiting below link {% endhint %} {% content-ref url="/pages/-Mfx\_WqwX1AtyFTcwhii" %} [Webhook](/devices/webhook) {% endcontent-ref %} ### Setting Tariff to the device 1. Navigate to device page 2. Hover on **Tariff** and click on ![](https://3941591838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfxR1BFQq6fVoNHpxrr%2Fuploads%2Fgit-blob-6db22d925668d1ab6a69f3278e5c82fe8a84c588%2Fedit.svg?alt=media) icon. 3. In the **Search and Select a tariff** pop-up page 1. Enter your tariff name that you want to add 2. Wait for the result 3. Select the **Tariff Card** from the search result {% hint style="info" %} Learn more about how you can paid actions for your device using our tariff manager. {% endhint %} {% content-ref url="" %} {% endcontent-ref %} ### Adding Frequently Asked Questions 1. Navigate to device page 2. Hover over **FAQ** and click on ![](https://3941591838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfxR1BFQq6fVoNHpxrr%2Fuploads%2Fgit-blob-6db22d925668d1ab6a69f3278e5c82fe8a84c588%2Fedit.svg?alt=media) icon. 3. In the **Manage FAQs** po-up page * Enter text to search questions by name * Wait for the results * Click on the add icon on the right of the question * On success full addition a new entry should be added on top tof the search bar. {% hint style="info" %} Learn how you can [create](/frequently-asked-questions/create-a-question) FAQ's. {% endhint %} {% content-ref url="" %} {% endcontent-ref %} ## **Device Display Card** ### QR Code This is your device's public URL. This public URL works according to the [configuration](#general) explained above. ### Social Support Links We strongly recommend you to provide support through some channel. You can connect with the customers through the device's social profiles. We support the following social links on our platform: * Facebook; your device's page id * Instagram; your device's profile id * WhatsApp; business contact number * Telegram; telegram support id * Email; support email address * Other; Any other link which has the information ## Other Information You can also view your device sales and the reviews submitted by your customer on this page. We recommend using your payment gateway's dashboard to better understand the money flow. # Webhook ## What is a Webhook? A webhook (also called a web callback or push API) is a way for an app to provide other applications with real-time information. A webhook delivers data to other applications as it happens, meaning you get data immediately. Unlike typical APIs where you would need to poll for data very frequently to get it real-time. #### Example If you have your webhook set up properly, you will receive a notification every time a user completes the payment process. # Set Up and Edit Webhooks You can set up and edit webhook from the Thy Street Dashboard. ### Prerequisites Before you begin, get access to the [Thy Street Dashboard](https://thystreet.com/dashboard) by creating an [account](https://thystreet.com/register); make sure you have gone through: {% content-ref url="/pages/-Mg-5L3MKYhWcPjI4UK6" %} [Create Device](/devices/create-device) {% endcontent-ref %} {% content-ref url="/pages/-Mg-5w3Cc96YrcBiiYF7" %} [API Credentials](/accounts/account-settings/api-credentials) {% endcontent-ref %} ## Set up Webhooks 1. Login into the [Thy Street Dashboard](https://thystreet.com/dashboard) and navigate to the [Devices](https://thystreet.com/devices) page. 2. Search and click on your device card. 3. Under the **Details** section, hover on **Integration** and Click on ![](https://3941591838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfxR1BFQq6fVoNHpxrr%2Fuploads%2Fgit-blob-6db22d925668d1ab6a69f3278e5c82fe8a84c588%2Fedit.svg?alt=media)icon. 4. In the **Device Integration** pop-up page 1. Enter the URL where you want to receive the webhook payload when an event is triggered. We recommend using an HTTPS URL. You can use other protocols by writing your own [custom adapter](/devices/webhook/custom-adapter). 2. Enter a **Secret** for the endpoint. The secret is used to validate that the webhook is from Thy Street. Learn more about [how to validate and test webhooks](/devices/webhook/validate-and-test-webhooks). 3. Click on **Save Endpoint** to save changes. {% hint style="info" %} **Webhook URLs**\ \*\*\*\*Webhooks can only be delivered to public URLs. {% endhint %} {% hint style="warning" %} All webhook responses must return a status code in the range of 2XX within a window of 6 seconds. If we receive response codes other than this or the request times out, it is considered a failure. {% endhint %} {% hint style="info" %} **Secret for Webhooks** * When setting up the Webhooks, you will be asked to specify a secret. Using this secret, you can validate that the webhook is from Thy Street. The **Secret** should never be exposed publicly. * The webhook secret doesn't need to be the API key provided for your account. {% endhint %} ## Edit a Webhook You can edit your webhook to replace the webhook URL and modify the secret. To edit webhooks: 1. Log into the [Thy Street Dashboard](https://thystreet.com/dashboard) and navigate to your **Device** page 2. Under the **Details** section, hover on your webhook link and click on ![](https://3941591838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfxR1BFQq6fVoNHpxrr%2Fuploads%2Fgit-blob-6db22d925668d1ab6a69f3278e5c82fe8a84c588%2Fedit.svg?alt=media) 3. The **Device Integration** pop-up page is displayed. You can modify the following: * Webhook URL * Secret 4. Click on **Save Endpoint** to save changes. {% hint style="info" %} **Next Steps** You should validate and test your webhooks before you go live. {% endhint %} {% content-ref url="/pages/-Mg-C-OKBNAfodXybLAR" %} [Validate and test webhooks](/devices/webhook/validate-and-test-webhooks) {% endcontent-ref %} # Validate and test webhooks You need to validate and test the webhook before you can start using them. ## Test Webhooks You can test the webhooks to verify payloads or check if your webhook integration is working. You can test webhooks: * [using request interceptor tools](#request-interceptor) * [on an application running on localhost](#application-running-on-localhost) ## Request interceptor There are many free webhook testing tools available online. We will be using one such service, [requestbin.com](https://requestbin.com), to test webhooks. To test webhooks: 1. Open [requestbin.com](https://requestbin.com) 2. Click **Create Request Bin** and log in to create a private bin. Alternatively, you can opt for a public bin. 3. Copy the endpoint created for you. 4. Proceed to [set up webhooks](/devices/webhook/set-up-and-edit-webhooks), but paste the endpoint you copied in the previous step in the Webhook URL field. 5. After completing the device setup, you should start receiving the tariff's payload on your requestbin.com site. ## Application Running on Localhost You cannot use localhost directly to receive payload as webhook delivery requires a public URL. You can handle this by creating a tunnel to your localhost using tools such as [ngrok](https://ngrok.com) or [localtunnel](https://localtunnel.github.io/www/). You can refer to their respective documentation to get started. Use the URL endpoint generated by these tools in the webhook URL while setting up your webhooks. ## Validate Webhooks When your webhook `secret` is set, Thy Street uses it to create a hash signature with each payload. This hash signature is passed with each request under the `X-ThyStreet-Signature` header that you need to validate at your end. The hash signature is calculated using HMAC with SHA256 algorithm, with your webhook secret set as the key and the webhook request body as the message. You can validate the webhook signature yourself using an [HMAC](https://en.wikipedia.org/wiki/Hash-based_message_authentication_code) as shown below: ``` key = webhook_secret message = webhook_body // raw webhook request body received_signature = webhook_signature expected_signature = hmac('sha256', message, key) if expected_signature != received_signature throw SomeSecurityException end ``` {% hint style="warning" %} **Do Not Parse or Cast the Webhook Request Body** While generating the signature at your end, ensure that you are using the **raw webhook request body**. **Do not parse or cast the webhook request body.** {% endhint %} {% hint style="info" %} **Handy Tips** If you have changed your webhook secret, remember to use the old secret for webhook signature validation while retrying older requests. Using the new secret will lead to a signature mismatch. {% endhint %} # Custom Adapter An adapter is a piece of software that converts HTTP protocol to your own. There are various ways to achieve that. One such example of a custom adapter that converts HTTP to MQTT protocol, written in node js, is available at . This is just for explanatory purposes and not recommended to be used in production, and pull requests are welcomed. {% hint style="info" %} Would you please help us decide the next protocol for **device integration**? Please help us by participating in the [protocol poll](https://linkto.run/p/JDV7XR1J) () today. {% endhint %} #### Example * MQTT: # What is a tariff card? *Tariff* is the rate or charges offered to the customer to use different services provided by the device. Commonly, a tariff is a charge of room rates and other facilities. Prices with their tax information for all the device services are incorporated in a card known as the **Tariff card**. #### Example For an automatic three types of grains filling and packing system, the tariff card will contain three entities of grains, with their price and taxes. # Create Tariff Card ## Prerequisites Before you begin, get access to the [Thy Street Dashboard](https://thystreet.com/dashboard) by creating an [account](https://thystreet.com/register). ## Create New Device 1. Login into the [Thy Street Dashboard](https://thystreet.com/dashboard) and navigate to the [Tariff Manager](https://thystreet.com/tariff) page. 2. Click on the **New Tariff Card** button. 3. In the **Add Tariff Card** pop-up page 1. Enter your **Tariff name**. 2. Describe the tariff card in **Description**. 4. Click on **Add Tariff** to create the tariff. {% hint style="info" %} **Next steps** * [Add services](/tariff-manager/edittariff) to the tariff card. * [Attach tariff](/devices/device-options#setting-tariff-to-the-device) card to a device. {% endhint %} # Edit Tariff Card # Account Settings # API Credentials # Payment # What are FAQs? A FAQ page is one of the most important and must have sections for your device page. If you still don't have a FAQ section, you;re already missing out on many benefits it can bring you. Like saving hours worth of support requests or emails and helping potential buyers make a decision all by themselves. In this detailed guide, we're going to dive deep into the whole concept of FAQs To discover their main purpose and to find out how it can help generate more sales for your business. ### What does FAQ stand for? FAQ stands for **F**requently **A**sked **Q**uestions. A FAQ section s usually a list of common questions people have asked about your device or the service it provides. Think f a FAQ section as an automated customer support page or a simplified device manual. Where users can figure out answers to product-related questions all by themselves. ### Why are FAQs important? Many device owners often get asked the same questions over and over again by potential customers. And they are always the same common questions like "How to perform a specific action on the device?", "What if my items are not dispensed?" Most device owners spend hours of their valuable time every day answering these general questions. While it could've been easily avoided by enabling a FAQs section. Think about how much time and money you can save from allowing your customers to help themselves using a FAQ page. However, FAQ sections are more than just about providing customer support. ### How to take advantage of FAQs? In addition to saving lots of pre-sales calls and support tickets, FAQ pages can also be a great way to promote your products as well. There's a reason why many businesses constantly update and improve their FAQ pages, it's to build awareness for the brand and promote your devices. # Create a question ### Prerequisites Before you begin, get access to the [Thy Street Dashboard](https://thystreet.com/dashboard) by creating an [account](https://thystreet.com/register). ### Create New Question 1. Login into the [Thy Street Dashboard](https://thystreet.com/dashbaord) and navigate to the [FAQs](https://thystreet.com/faq) page. 2. Click on the **Add Question** button 3. Enter your question and answer in the pop-up 4. Click on **Add** This will create a new question for your question bank > Next steps > > * [Add questions](/devices/device-options#adding-frequently-asked-questions) to a device and enable FAQ section # Liquid Vending Device # Hardware # Software