What is Generic Protocol Tag Analog Mapping?

Generic tag analog mapping is a particular method of associating BLE tags and BLE gateways with one another. Please see our article on Bluetooth® Tag Analog Mapping for an overview. It is called 'generic protocol tag' because this approach allows the fast and code-less integration of any make and model of tag under a shared protocol.

Which Devices Support Generic Protocol Tag Analog Mapping?

Steps for Analog Mapping (Continuous)

1.  Please ensure that your device firmware and Bluetooth® firmware are both updated to the latest versions available.
    
2.  For users going through this process for the first time, we recommend turning on Data Capture and Debug Logging for a single day so that you can gain immediate feedback as to the success of your mapping.
    
3.  We furthermore suggest that users who that have not worked with BLE tags before first attempt to create Tag List logs that contain your target tag to eliminate potential issues with your general Bluetooth settings or the tag itself.
    
4.  Navigate to the Edit System Parameters window and enable the BLE Continuous Tag Scanning tab. This process should also work with the periodic tag scanning tab, but there are few reasons to do this with a hard-wired device.
    
5. Change Enable Scanning to Yes
    
6. Change Log Taglist to No
    
7. Change Analog Mapping to Yes
    
8. Change TagList/Analog Log Period (minutes) from 60 to 3 (purely for testing, you should set this to whatever best suits your application afterwards)
    
9. Change Upload on TagList or Analog Mapping to Yes
    
10. Change the first available Other Tag Type dropdown to Generic Protocol Tag
     
11.  From the Add Advanced Parameters tab, select BLE Generic Protocol Tags
     
12. Find the Generic Protocol Tag Type that corresponds with the Other Tag Type number you selected in step 9 and change the dropdown value to match your target BLE tag type from either an option or the list, or Custom. If Custom, please contact Digital Matter support for assistance in creating the custom instructions to automatically integrate your new tag type.
     
13. From the Add Advanced Parameters menu, please select BLE Analog Mapping 1 
    
    
     
14. Enter the MAC Address of your BLE tag. If it is not written on the tag, you can use an app like nRF Connect on either Desktop or Android to find your tag and list its MAC address.
     
15. Select an unallocated analog number on your BLE gateway to use for your sensor data. If your sensor produces multiple attribute values, the analog selected here will be the first value, with subsequent attribute values going into the next numbered analog in line.
     
16. Select your BLE tag type from the Instructions list, or choose Custom to provide your own mapping instructions. As before, custom instructions require guidance from the Digital Matter team, but allow flexible integration with any make and model of tag provided you can interpret your tag's technical documentation.
     
17. Click Update to save your settings.
    
    
     
18. Navigate to Logs from the Device View page and review the Logs until you can see that it has successfully taken the logs and reported a sensor scan. The length of time required for this step will depend on the frequency with which your device checks in with the server. You can hasten this with a bit of percussive encouragement to trigger a harsh event.
     
19. Once you see values that correspond with your expected datatypes in the analogs you have specified, you will know that you are successful. You may repeat this process two more times for subsequent BLE tags.
     
20.  The specific settings and values outlined above to enable continuous scanning are not the only settings that can be used with generic protocol analog tag mapping, and should almost certainly be changed for your application. To guide the refinement of the optimal settings for your application, please consult Continuous Bluetooth Scanning.

Steps for Analog Mapping (Periodic)

1.  Please ensure that your device firmware and Bluetooth® firmware are both updated to the latest versions available.
    
2.  For users going through this process for the first time, we recommend turning on Data Capture and Debug Logging for a single day so that you can gain immediate feedback as to the success of your mapping.
    
3.  We furthermore suggest that users who that have not worked with BLE tags before first attempt to create Tag List logs that contain your target tag to eliminate potential issues with your general Bluetooth settings or the tag itself.
    
4.  Navigate to the Edit System Parameters window and enable the BLE Tag Scanning tab. This process should also work with the periodic tag scanning tab, but there are few reasons to do this with a hard-wired device.
    
5. Change Scan Mode to Yes
    
6. Change Out of Trip Scan Period (minutes) to 3 (purely for testing, you should set this to whatever best suits your application afterwards)
    
7. Change Upload On Out of Trip Scan to Yes
    
8. Change Scan Length (seconds) to 15 (assumes a chirp rate of 5 seconds or less - see Choosing Bluetooth® Scan Length for optimizing this value)
    
9. Change the first available Other Tag Type dropdown to User Integrated Tag
    
10.  From the Add Advanced Parameters tab, select BLE User Integrated Tags(Adv).
     
11. Find the User Tag Type that corresponds with the Other Tag Type number you selected in step 9 and change the dropdown value to match your target BLE tag type from either an option or the list, or Custom. If Custom, please contact Digital Matter support for assistance in creating the custom instructions to automatically integrate your new tag type.
     
12. From the Add Advanced Parameters menu, please select BLE Generic Tag Analog Mapping 1 
    
    
     
13. Enter the MAC Address of your BLE tag. If it is not written on the tag, you can use an app like nRF Connect on either Desktop, iOS or Android to find your tag and list its MAC address.
     
14. Select an unallocated analog number on your BLE gateway to use for your sensor data. If your sensor produces multiple attribute values, the analog selected here will be the first value, with subsequent attribute values going into the next numbered analog in line.
     
15. Select your BLE tag type from the Instructions list, or choose Custom to provide your own mapping instructions. As before, custom instructions require guidance from the Digital Matter team, but allow flexible integration with any make and model of tag provided you can interpret your tag's technical documentation.
     
16. Click Update to save your settings.
    
    
     
17. Navigate to Logs from the Device View page and review the Logs until you can see that it has successfully taken the logs and reported a sensor scan. The length of time required for this step will depend on the frequency with which your device checks in with the server. You can hasten this with a bit of percussive encouragement to trigger a harsh event.
     
18. Once you see values that correspond with your expected datatypes in the analogs you have specified, you will know that you are successful. You may repeat this process once more for a subsequent BLE tag.
     
19.  The specific settings and values outlined above to enable periodic scanning are not the only settings that can be used with generic protocol analog tag mapping, and should almost certainly be changed for your application. To guide the refinement of the optimal settings for your application, please consult Periodic Bluetooth Scanning.

Troubleshooting

If you have followed all of these steps exactly and can see message payloads in the logs that do not contain the analogs that you selected for mapping, check off these steps.

1.  Can you detect your BLE tag with another device like a phone app? If not, it may be a tag issue
    
2.  If you are using a configurable tag, have you set it into the right format for integration (i.e. ELA tags into manufacturer mode)?
    
3. Can your BLE gateway detect any tags at all? Turn on Tag List temporarily to ensure that you don't have an empty tag list. An empty taglist may imply overly zealous filtering - change Other Tag Types to a more generic setting - like ELA Tags for an ELA tag just to get it to populate (The ELA Tags option as opposed to the Generic Protocol Tag option will not work for analog mapping itself however, so set it back to Generic Protocol Tag once you can confirm that the tag is detectable with sensor values in the tag list).
    
4.  Do all of your numbers line up? Other Tag Types 1 must link to Generic Protocol/User Integrated Tag Type 1 for example. 
    
5.  If you've made it down here then please contact Digital Matter support, we're here to help.