theterg / bugswarm-renesas-G14

A BUGswarm connector for Renesas 8- and 16-bit microcontrollers.

bugswarm-renesas:

Table of Contents generated with DocToc

• bugswarm-renesas:
  • Supported Boards
  • The RL78/G14 board with built-in Gainspan module
    • Usage Instructions
    • Programming Instructions
    • Implementation Details
      • Known Issues
    • Troubleshooting
  • The RL78/G13 board with Redpine companion card
    • Usage Instructions
    • Programming Instructions
    • Implementation Details
      • Known Issues
    • Troubleshooting
    • Relevant Documentation

A bugswarm connector for Renesas 8- and 16-bit microcontrollers. This code turns a compatible evaluation board into a real-time internet enabled device. Once the connector is deployed to a device, the device will automatically connect to the bugswarm platform and share it's peripherals using a standardized API. This enables developers to create applications for the evaluation board in a wide variety of languages, without needing to download an SDK or physical access to the device.

Supported Boards

• RL78/G13 Demonstration Kit (YRDKRL78G13)
  • Redpine companion WiFi Card (RS-RL78G13-2200CC)
• RL78/G14 Demonstration Kit (YRDKRL78G14)
  • Built-in Gainspan GS1011-MIPS module

The RL78/G14 board with built-in Gainspan module

This is the most recent bugswarm-enabled device. The firmware is currently in beta, using the IAR RL78 Workbench development environment. For the final firmware release, the code will be ported to the CubeSuite+ environment and Applilet3 driver generation tool. Notable improvements:

• Swarm credentials are automatically generated based on the device mac address, no user intervention required
• Wifi access point can be set using the web provisioning feature of the gainspan module
• A single firmware can be used for all RL78G14 development boards.

Usage Instructions

1. Connect the RDK board to a USB power source using a USB-Mini cable.

   

2. The RL78 will enter web provisioning mode on first boot. Using a smartphone, tablet, or laptop, connect to the wireless access point indicated on the LCD screen.

   

3. Open a web browser and go to the URL indicated on the LCD screen. Click on the Wireless and Network Configuration link.

   

4. To scan for an access point to connect to, click on Select an Existing Network

   

5. Pick a wireless AP from the list and click on it's Select button:

   

6. Enter the wireless password, leaving the other fields at default values. Click on next:

   

7. Click on Save And Apply to confirm the selection.

   

8. You should see the following message displayed on the LCD screen. Press the RESET button.

   

9. After rebooting, the device will automatically connect and begin producing data. Note the ID: field on the third line, and keep an eye on the screen for any errors.

   

10. Navigate to buglabs.github.com/bugswarm-renesas/. In the first dropdown box, select the YRDKRL78G14 board and click "Go!".

    

11. Click on the second dropdown box. You should see the ID from the LCD screen in the list. Select that entry and click "Go!".

    

12. You should now see live data from your Renesas device. See the tutorial folder for examples of how to use this data in your own application.

    

Programming Instructions

Forthcoming.

Implementation Details

Pseudocode for the firmware:

1. Check status of switches. If SW1 is held down, enter Gainspan web demo. If SW2 is held down, enter web provisioning mode
2. Initialize hardware and read wireless AP data from nonvolatile storage. If no SSID has been saved, enter web provisioning mode
3. Read wifi MAC address and execute API call to swarm server. Swarm credentials will be created if the device is new, and then returned.
4. If Swarm credentials could not be retreived from server, use default ID of "UnknownDevice".
5. Open a streaming "producer" session with the swarm API, and wait for message from server acknowledging the "presence" of the module.
6. Enter production loop, in which each sensor on the board is sampled and transmitted to the server, every second.

Known Issues

1. The watchdog timer has not been enabled in the beta release, adding this will improve reliability when the module is suddenly disconnected from the internet.
2. Serial debugging occurs over UART0 (at 115200 baud) which is used by the debugger. We haven't been able to use the USB debugger tool to read this data, we instead used a seperate USB->Serial converter connected to pins 54 and 55.

Troubleshooting

1. If the device appears on the Renesas Web Portal as "UnknownDevice", try rebooting it. Occasionally the first API call can fail if the wireless access point has not finished opening the connection.
2. If an error is printed to the LCD screen on line 4 or line 8, and the error does not go away for a few minutes, try manually resetting the board.
3. If the RDK board never appears on the web portal, use a smartphone or laptop to verify that the selected wireless access point has an internet connection, particularly to demo.bugswarm.com or developer.bugswarm.net.

The RL78/G13 board with Redpine companion card

This was the first board to receive a bugswarm connector. The development environment is the Renesas CubeSuite+ compiler with Applilet3 driver generation toolkit. Notable limitations:

• Swarm credentials must be pre-programmed into the firmware of each board, using a development environment
• Wifi AP credentials must be pre-programmed as well, defaulting to SSID "renesasdemo" Password "renesaspsk"

Usage Instructions

1. Set up a wireless access point, or Mifi tether with the SSID renesasdemo and password renesaspsk. The wireless security can be WPA1 or WPA2 Personal. See the deployment instructions below to connect to a different ESSID.

2. (Optional) Connect a laptop or cellphone to this wireless access point, verify it can connect and verify that it has internet connectivity.

3. Make sure that Switch 2 of SW5 is set to the up or 'On' position. See the quick start guide for more details.

   

4. Using a USB Micro cable, connect the RL78 board to a USB power source. This can be a PC, Laptop, or USB wall charger.

5. The demo board will take several seconds to connect to the wireless access point. When it has successfully connected, LED6 (the green led to the left of the LCD screen) will blink.

6. Navigate to buglabs.github.com/bugswarm-renesas/

7. Wait a few seconds and then click on the Select an RL78/G13 board to view" dropdown menu

8. Select the entry that matches the MAC address printed on the Wifi Companion card, and hit Go!

9. The graphs should update with data as it is sent by the RL78 board.

See the troubleshooting section below if board does not appear in the list, or data is not produced.

Programming Instructions

1. Download and install the newest version of CubeSuite+ from the following link

2. Open CubeSuite

3. Download the newest version of the bugswarm connecter from this repository link

4. Extract the zip file to a reasonable location, like My Documents/CubeSuite/bugswarm-renesas/

5. Within CubeSuite, select File -> Open and navigate to bugswarm-renesas.Buglabs.mtud within the directory from the previous step.

6. In the pane on the left hand side of the application, double click on the file rsi_global.h within the redpine folder.

   

7. The board is configured to connect to ESSID renesasdemo with password renesaspsk. If you would like to change these settings, modify the variables PSK, SCAN_SSID, and JOIN_SSID accordingly

   

8. Log in to demo.bugswarm.com

9. Click on the New Resource button

10. Fill out the "Name" field with a unique value, such as the MAC address printed on the redpine companion card

11. Fill out the "Description" field with "RL78/G13 Demonstration Board"

12. Click on "Create"

    

13. Click on the "My Swarms" tab.

14. Select the "rl78_web_portal" swarm.

15. Click the "Edit" button.

    

16. Find the resource that was created previously in the right hand side of the screen, and click on the grey "producer" button (do NOT select the "consumer" button).

17. Click on the "Update" button.

    

18. In the next screen, find the resource we just created and copy the text next to the ID: label.

    

19. In the CubeSuite IDE, double click on the file r_main.c within the gen folder.

20. Replace the text immediately following const char resource_id[] = with the ID copied from the bugswarm webpage, similarly in quotes.

    

21. Connect the Redpine Wifi Card to the App header slot on the RL78/G13 board (See this Diagram). The components on the wifi card should be facing inwards.

    

22. On the RL78G13 demo board, make sure that switch 2 on SW5 is in the downward (or 'Off') position. See the quick start guide for more details.

23. Connect the RL78G13 demo board to the PC using a USB cable

24. Within CubeSuite, press the <F6> button. The project should compile and deploy to the demo board.

25. When the download has completed, the screen should change and should highlight a single line in r_main.c in yellow. When this happens, press the <F5> key.

    

26. The application should start running.

Implementation Details

This bugswarm connector works by opening a socket to api.bugswarm.net, creating a new production session, and continually publishing sensor data (See the swarm API documentation). This application currently requires the following credentials to be acquired and inserted into the source code before use:

• Wireless ESSID (rsi_global.h)
  • default: renesasdemo
• Wireless password (if applicable) (rsi_global.h)
  • default: renesaspsk
• Swarm Producer API Key (r_main.c)
  • default: 7a849e6548dbd6f8034bb7cc1a37caa0b1a2654b
• A valid Swarm ID (r_main.c)
  • default: 27e5a0e7e2e5445c51be56de44f45b19701f36d3
• A valid Resource ID, having already been added to the supplied swarm. (r_main.c)

All Renesas devices will share the same producer API Key - this is linked to the Renesas account. In order for all of the Renesas RL78/G13 demo boards to be listed together, they all need to be added to the same swarm. Devices should use the default swarm ID above, unless they are being configured for a custom application. Resource IDs, on the other hand, MUST be unique for each demo board. When provisioning a new demo board, a new resource ID will need to be generated. We suggest that the resource ID have a unique name, such as the MAC address of the wireless module, but the resource ID will always be a unique 40 character string.

Known Issues

• The Redpine device cannot send data at the same time that data is being recieved. Data reception is fully asynchronous, and could occur at any time. The current libraries do not successfully detect that data reception is in progress while sending. When this occurs, depending on the timing, it may cause the redpine device to abruptly close the socket. The current code will automatically attempt to reconnect. In the future, we should aggressively check that the UART is not in the middle of reading a line before sending any new AT commands. This needs to occur at the UART API level of the redpine libraries.
• The current Redpine libraries cannot reliably read a multi-line response from an open socket. The first line of a repsonse is prefixed with AT+RSI_READ and is successfully detected. However, since the response is not byte-stuffed, subsequent lines within the same packet are detected as junk data (since they are not prefixed with AT+RSI_READ). This requires a larger overhaul of the rsi_read() function.
• Even with a modified rsi_read() function, no mechanism exists to ensure that an entire packet-worth of data has been successfully read. The total packet size is returned in the initial AT+RSI_READ command, but very often data is either lost or read twice while reading. Data is being read successfully by the rsi_receive() function, but a valid state machine has not been created for the rsi_read() function with multi-line packets.

Troubleshooting

If the RL78 demonstration board does not appear or remain online, you will need to connect to a serial console on the demo board.

1. Obtain an RS232 to USB converter
2. Connect the RS232 adapter to the RS232 port on the RL78 demontration board, and into a computer or laptop.
3. Open a serial terminal emulator like HyperTerm or Putty and connect to the USB-Serial port. Use Baud rate 115200, 8 bits, no parity, 1 stop bit, and no hardware flow control. Here is an example tutorial
4. Press the Reset button on the RL78 demo board, and observe the serial output
5. Reproduce the error, and copy/paste all of the relevant serial output into pastebin.com. press "Submit".
6. Contact buglabs support, and provide the URL of the pastebin website.

Relevant Documentation

• bugswarm API documentation
• bugswarm javascript library
• bugswarm preliminary configuration interface
• Redpine Signals Companion Card resources
• Renesas RL78G13 Demo Kit resources
• YRDKRL78G13 Quick Start Guide (how to install the SDK)
• YRDKRL78G13 Getting Started DVD
• RL78G13 CPU Hardware Manual
• Further redpine documenation only available by contacting redpine suppport.