Frequently Asked Questions

[中文版本]

Why doesn't Claiming work with our deployment?

Answer

Here are the primary reasons why claiming is not available:

  • Self-claiming requires a separate authentication service with information of secret keys programmed in the efuse of all ESP32-S2s during chip manufacturing. Replicating the service in private instances isn't straightforward.
  • Host driven or assisted claiming gives admin rights to the user claiming the node, which is undesirable in commercial deployments.

In the private instance, instead of claiming (which happens in the field), the credentials will be pre-flashed on the modules and the public certificates will be registered with the cloud backend service using the RainMaker Admin CLI. There are multiple options for generating and flashing the credentials.

  1. Buy pre-provisioned modules from Espressif and register the certificates' file with the admin CLI.
  2. Use the admin CLI to generate the unique binaries and register the certificates. Flash the binaries on the modules one by one using esptool or multiple at once using a programmer jig.

Please get in touch with your Espressif Sales contact for more information on this.

I have completed the deployment of RainMaker Services, but I did not receive any emails for the deployment details. What do I do?

Answer

Please check if the deployment details email are in the junk email box. If the junk email box doesn't contain the email for the deployment details, then further investigation is needed.

  1. Check if the following steps are followed - Configuring the Email sending Service in the RainMaker region/s
  2. Make sure if the required RainMaker components are deployed successfully, from the CloudFormation dashboard, as mentioned in deployment guide- Verifying RainMaker Deployment is completed.
  3. If all the required stacks are deployed successfully, then the password for super admin can be reset from the RainMaker dashboard.

Steps to reset password:

  1. On the RainMaker dashboard login page, select the option "Forgot Password".

  2. On the next page, you will be prompted to enter the associated Email ID. Enter the super-admin email ID. You will receive a verification code on your email address.

  3. On the next page, Enter a preferred password and verification code.

  4. You will be able to log in to RainMaker dashboard with new credentials.

Getting the RainMaker API URL (Base URL)

  1. Login to RainMaker dashboard with admin credentials.

  2. Go to the Deployment Settings tab.

Deployment details dashboard

  1. For API gateway, there are two types supported:
    1. REST gateway - This is the legacy gateway used by default for all deployments.
    2. HTTP gateway - Newly introduced cost effective (~70% cheaper) gateway. (Note: This requires user migration to the new pool. For steps: User Pool Migration Guide)

Please note: ESP API Rate Limiter add-on is not available when you choose HTTP gateway. This might lead to intentional API request overload by malicious users.

  1. You can choose API Endpoint of your choice

  2. You may contact the ESP RainMaker support team (esp-rainmaker-support@espressif.com) for further doubts.

My Google Sign-in is not working from the Mobile App

Answer

For Google-sign to work correctly, make sure the Callback URLs are configured correctly in the Mobile app and Cognito/RainMaker Dashboard.

The Callback URL configured in the RainMaker Dashboard or Cognito configuration (reference - Configuring Cognito Callback URL) should match the configuration in the Mobile App (reference - Android configuration, iOS configuration.

e.g. If your application ID is com.espressif.rainmaker, your callback URL will be - rainmaker://com.espressif.rainmaker/success for Android Mobile App and com.espressif.rainmaker.app://success for iOS Mobile App.

My Apple Sign-in is not working from the Mobile App

Answer

For Apple-sign to work correctly, make sure the Callback URLs are configured correctly in the Mobile app and Cognito/RainMaker Dashboard.

The Callback URL configured in the RainMaker Dashboard or Cognito configuration (reference - Configuring Cognito Callback URL) should match the configuration in the Mobile App (reference - iOS configuration.

e.g. If your application ID is com.espressif.rainmaker, your callback URL will be - com.espressif.rainmaker.app://success

Where do I find the callback URLs for third Party Integration?

Answer

Callback URLs are required for third-party login.

If you have not configured Cognito callback URLs, please configure with the steps given here: Configure Cognito callback URL

For third-party login for Android app, please check : Getting redirect URI for Android app

For third-party login for iOS app, please check : Getting redirect URI for iOS app

The callback URLs for each app client can be found on RainMaker Dashboard. The steps to find callback URLs are as follows:

  1. Login to RainMaker dashboard with the super-admin credential.

  2. From the left hand side menu, select "Deployment Settings".

Dashboard Deployment Settings

  1. Go to the "Cognito Configurations" tab.

Cognito Configurations tab

  1. The callback URLs configured for each app client will be listed in the "Cognito App Client Configurations" section.

Cognito App Client

Where do I find the Authentication URL for phone app configuration?

The authentication URL is required for third-party sign-in and App to App account linking for Alexa. Configuring Cognito Domain is required to create the authentication URL.

If you have not configured Cognito Domain, please perform the steps to configure Cognito Domain as given here: Configuring Cognito Domain

You can get the configured domain name from RainMaker Dashboard. Here are the steps to get your configured Cognito Domain:

  • Login to RainMaker Dashboard with super-admin credentials.

  • Go to Deployment Settings tab

  • Go to Cognito Configurations tab.

  • You will be able to see your Cognito Domain name.

The Authentication URL can be formed by appending /oauth2 to your domain URL. Note that Domain URL is complete HTTPS URL and not your domain name.

Authentication URL := https://<your_company_domain_name>.auth.<aws_region>.amazoncognito.com/oauth2

Where do I find the Client ID for phone app configuration?

The ClientID is the unique identifier for the RainMaker User pool app client.

You can get the clientID for your User pool app client from RainMaker dashboard. Here are the steps:

  • Login to RainMaker Dashboard with super-admin credentials.

  • Go to Deployment Settings tab.

  • Go to Deployment Details.

dashboard deployment settings

  • The App Client Id in the Cognito Details section gives value for client ID.

Where do I find the Client ID for Alexa and GVA?

  1. Login to RainMaker dashboard with the super-admin credentials.

  2. From the left hand side menu, select "Deployment Settings".

Dashboard Deployment Settings

  1. Go to the "Cognito Configurations" tab.

Cognito Configurations tab

  1. Note down the Client ID for clients with names esp-rainmaker-alexa-skill and esp-rainmaker-google-action.

appclient

Where do I find the custom message template in Cognito?

Answer

The configured custom message template can be found on AWS Cognito Console. The steps to find custom message template are as follow:

  1. Login to AWS console.

  2. From the AWS console, search for Cognito Service ( AWS Console -> Service -> Cognito).

post_deoploy1

  1. Click on manage user pools.

post_deoploy2

  1. Search for rainmaker-user-email-mobile-pool and click on it.

post_deoploy3

  1. Click on Messaging option & scroll down to Message templates .

post_deoploy4

  1. The details about the configured custom message, like SES region, FROM email address ARN, Email subject, Email message can be found on the Message Customization page.

Message Template

Message Template

Deployment of "ESP-RainMaker-Core" is failing with below error, What should I do?

deployment_error_1

Answer

  1. Login to AWS console.
  2. From the AWS console, search for "CloudFormation" and click on "serverlessrepo-ESP-RainMaker-Core"
  3. Then goto resource tab and search for "espstatsinfo" and click on the stack link provided. deployment_error_2
  4. Goto "Events" tab and search for "CREATE_FAILED" deployment_error_3
  5. If the error is shown as above, then the issue is related to lambda concurrency. For which you may need to raise a support ticket with AWS.

Below are the steps for raising a Support ticket

  1. Go to your AWS console and search for "Support" support_1
  2. Then click on "Create Case"
  3. Then select "Service limit increase’ and then select Limit Type as "Lambda" as shown below: support_2
  4. Then fill in the case details:

support_3

  1. Add the request:

    1. Select your deployment region
    2. Limit: Concurrent Requests (Expected Duration * Expected Requests per Second)
    3. New Limit Value: 1000 support_4

  2. Add Case Description.

    We are trying to deploy our product: https://rainmaker.espressif.com/ Since the current limit for concurrency is set to 10 we are not able to deploy our product. Can you please set the concurrency limit to 1000.

  3. Submit the request.

When I am trying to link my Amazon Alexa account with my RainMaker account from the RainMaker Mobile app, why do I need to login again using the hosted UI?

Answer

For the account linking process, we need to get the RainMaker Auth code from AWS Cognito.

To get the Auth code, there is a need to login again using Hosted UI.

During Alexa account linking if I unlink the account and want to link the skill with a different account, the hosted UI is logged into using the cached browser data. How do I link with a different account?

Answer

In order to log into a different account on the hosted UI you can do the following:

For iOS:

  • Go to iPhone Settings
  • Go to Safari
  • Go to Advanced
  • Go to Website Data
  • Search for the domain name of the Oauth URL (e.g. auth.rainmaker.espressif.com)
  • Swipe right and then press delete

For Android:

  • Go to Chrome browser app (the browser app which you are using)
  • Click on option menu (icon with 3 dots)
  • Go to History
  • Click on "Clear browsing data"
  • Click on "Clear data"

After clearing browsing data, the next time you go through the account linking flow the login screen for the hosted UI will show up and you can log into the other account.

What are App Bundle IDs in iOS?

Answer

A Bundle ID or bundle identifier uniquely identifies an application in Apple's ecosystem. This means that no two applications can have the same bundle identifier.
To avoid conflicts, Apple encourages developers to use reverse domain name notation (com.espressif.rainmaker.softap) for choosing an application's bundle identifier.

What are URL Schemes in iOS?

Answer

URL schemes provide a way to reference resources inside your app. Users tapping a custom URL in an email, for example, launch your app in a specified context. Other apps can also trigger your app to launch with specific context data; for example, a photo library app might display a specified image.

Find more information on URL Schemes here.

What are App Groups in iOS?

Answer

This identifier specifies that your app belongs to the corresponding group. App groups allow multiple apps produced by a single development team to access shared containers and communicate with each other. Apps may belong to one or more app groups.

For iOS, format the identifier as follows:

group.<group name>

To add this entitlement to your app, enable the App Groups capability in Xcode, and add the groups your app belongs to.

Where can I find iOS Team ID?

Answer

  • Go to Apple Developer Account.
  • Click on Account.
  • Click on Membership on the left navigation screen.
  • Team ID will be displayed under Membership Information.

I am not able to find the ESP-RainMaker-Base-API stack in the CloudFormation.

Answer

  • We have disabled access to the ESP-RainMaker-Base-API after the initial deployment of RainMaker.
  • If you are cleaning and redeploying the RainMaker, please contact the Espressif RainMaker team (esp-rainmaker-support@espressif.com) and request access to the ESP-RainMaker-Base-API stack.
  • There is no need to upgrade the ESP-RainMaker-Base-API if you are only performing Rainmaker upgrades.

I have configured the iOS push notifications, still facing issue for mobile notifications, What should I do?

Answer

Please go through the points below to ensure that you have followed all of the push notification configurations steps in the correct order.

  • Check push notification certificate is created for main app bundle id.
  • Check both platforms are created in RainMaker dashboard i.e. Production and Sandbox.
  • Check if APNS_SANDBOX notification is working in debug mode.
  • Check if certificate has not expired from Apple Developer console.
  • Check if push notifications events are enabled in RainMaker dashboard.

I haven't yet started using Rainmaker, But I'm still receiving emails from AWS saying your AWS free tier limit exhausted for certain services like SQS, What should I do?

RainMaker uses AWS SQS queues and lambdas to process the messages in the queue. Lambda periodically checks for new messages in the queue. As the customer is not using the system so there is no message in the queue. Here, the lambda polling receives an empty message which is billed as ReceiveMessage requests that don’t return a message. These empty receives are charged per Amazon SQS pricing even if messages aren’t sent or received from your SQS queue.

These empty read counts will naturally decrease as the customer starts using the Rainmaker.

AWS refer link: https://aws.amazon.com/premiumsupport/knowledge-center/sqs-high-charges/

The RainMaker support team from Espressif has requested read-only access to the AWS console; How do I create an IAM user with read-only access to all resources?

Answer AWS Identity and Access Management (IAM) is a powerful tool for securely managing access to AWS services and resources. To set up an IAM user, follow these steps:

  • Login to AWS Console and type "IAM" in the search box.
  • In the IAM dashboard on the left side of the screen, navigate to the Users section and click the "Add User" button.
  • Here, provide a user name and select the "AWS Management Console access" checkbox as the user needs to access the AWS Management Console. Then, click the "Next: Permissions" button.
  • On the Permissions page, choose "Attach existing policies directly" and type "ReadOnlyAccess" to filter the available policies. Locate the "ReadOnlyAccess" policy and enable the checkbox next to it. Proceed by clicking the "Next: Tags" button.

IAM-readonly-policy

  • You can skip the Tags page by moving forward to the "Next: Review" button.
  • Review the details for the read-only account user, ensuring they meet your requirements, and then click the "Create User" button.
  • Once the user is created, you will have access to their credentials. Click the "Download .CSV" button to obtain the necessary information and make sure to securely store the password. Keep in mind that the Secret Access Key and Password cannot be recovered if lost. You would need to reset the account in such a scenario.
  • Finally, share the user's credentials along with the URL provided under "Users with AWS Management Console access can sign-in at" link.

How to change the RainMaker Superadmin mail id?

Answer

It is not recommended to use personal mail ID for the Superadmin user, Please use a generic mail ID instead. Access to this generic email should be limited to very few set of people as this user will be the most privileged user in RainMaker deployment.
e.g. service@<company_domain_name>

To change the RainMaker Superadmin mail, you need to use the change_super_admin swagger API via postman.

  • In Postman, login to Rainmaker using current Superadmin credentials.

    FAQ_change_superadmin_1

  • In Postman, create new API request

    PUT - {{url}}/v1/admin/change_super_admin

    Header -

    KeyValue
    Authorization{{access_token}}

    Body -

    {

      "new_super_admin": "user@domain.com"

    }

    FAQ_change_superadmin_2

  • Upon initiating the Superadmin email address change request, both the current Superadmin and the new Superadmin will receive a verification code via email. It is necessary to enter and confirm the codes to proceed with the change request.

    Using the same API we can confirm the change request.

    FAQ_change_superadmin_3

Push notifications are not working for the Andorid App?

Amazon Simple Notification Service (Amazon SNS) now supports delivering mobile push notifications via Google Firebase’s HTTP V1 API. When creating a new platform application in the Amazon SNS console or API, you can choose token-based authentication to enable Amazon SNS to deliver mobile push notifications on your behalf, using the new Google FCM HTTP v1 API. You can also upgrade your existing platform application to use token-based authentication. Once you provide a valid key file, Amazon SNS will switch your application from the legacy FCM API to the new HTTP v1 API.

Starting June 1, 2024, Google plans to remove the ability to send mobile push notifications via the legacy FCM v1 APIs. In order to avoid impacting your existing platform applications, we recommend that you plan and migrate them on or before June 01, 2024.

Here are the steps to update the keys:

  • In the Firebase console, choose your project. In the left navigation pane, choose the gear icon, and then Project settings.

    firebase8

  • Choose Service accounts. Under Firebase Admin SDK, Click the Generate new private key.
    This will download a file with all the project details.

    firebase9

  • Log in to the Rainmaker Dashboard with your admin account. Go to deployment settings, then go to the Push Notifications tab.

    push_notification12

  • Under the Push Notification Plaforms Click on edit button for the Google Notification (GCM).

    push_notification17

  • Copy all the contents of the file that you downloaded. Click Update.

    push_notification18

How to check if a CloudWatch log group exists?

Answer

  1. Go to your AWS console and search for CloudWatch
  2. Go to the Amazon CloudWatch service -> Log groups
  3. Enter the log group name to be searched for

Get log group

  1. The log group will show up if it exists

How to create a CloudWatch log group?

Answer

  1. Go to your AWS console and search for CloudWatch
  2. Go to the Amazon CloudWatch service -> Log groups
  3. Click on 'Create log group'

Create log group

  1. Done

Third-party sign-in fails in my environment. The error extracted from the redirect URL is "user.client:Attribute+does+not+exist+in+the+schema.invalid_request". How can this be resolved?

Answer

The error "user.client:Attribute+does+not+exist+in+the+schema.invalid_request" is observed in RainMaker backend release 2.3.0.

The quick fix for this issue is to make manual changes on the AWS console to correct the Cognito IDP attribute mappings.

The steps to fix the issue are as follows:

  1. Go to the AWS console -> RainMaker deployment region -> Cognito -> User pools -> rainmaker-user-email-mobile-pool (if you use both email and mobile number based sign-in) or rainmaker-user-email-pool (if you use email-based sign-in) -> Sign In Experience -> Federated identity provider sign-in. This will list all Identity Providers configured with the user pool.

Third-party sign-in attributes

  1. Click on the Identity Provider name to correct the attribute mappings from the list on the above page.

  2. Go to Attribute mappings and click on "Edit". Update the list with the correct mapping values.

Google sign-in attributes

  1. Correct Attribute mappings for the IDPs are given here:

Google:

User pool attributeGoogle attribute
custom:admincustom:admin
custom:maintainercustom:maintainer
custom:user_idcustom:user_id
emailemail
email_verifiedemail_verified
namename
picturepicture
usernamesub

SignInWithApple:

User pool attributeApple attribute
emailemail
namename
usernamesub
  1. After the attribute mappings are updated as shown above, the issue should be resolved.

This issue will be fixed in the next RainMaker backend release.

End-users receiving emails from no-reply@verificationemail.com despite configuring the verified SES mail ID. How can this issue be resolved?

Here are the steps to correctly configure the SES email provider for your Cognito user pool:

  1. Navigate to Amazon Cognito. Select your user pool, specifically the rainmaker-user-email-mobile-pool. Click on Messaging in the menu list.

    SES_mail_configure1

  2. Configure the Email Provider: Check the Email provider section to view the current settings and the email address used to send emails. It is recommended to use the Send email with Amazon SES option as your email provider.

  3. Configure SES Email Address: Ensure that you select an email address from the verified list in Amazon SES. Once selected, click Save Changes. SES_mail_configure2

By following these steps, emails should be sent from the specified SES email address instead of the default no-reply@verificationemail.com.

End-users not receiving signup/login OTP on phone after the rainmaker upgrade. How can this issue be resolved?

You need to verify the below setting if your end-users are signed up with the mobile numbers.

  1. Navigate to Amazon Cognito. Select your user pool, specifically the rainmaker-user-email-mobile-pool. Click on Sign-up experience in the menu list.

  2. Ensure that the following setting is properly configured:

SMS_attribute1

  1. Verify the "Send SMS message if phone number is available, otherwise send email message" attribute under the messaging settings.
  2. If the setting is different, update it to this configuration.
  3. Click Save Changes to apply the update.

SMS_attribute2