Skip to content

Commit eb19fae

Browse files
TimVoschTimVosch
committed
docs(importer): create manual
1 parent 1bbe36f commit eb19fae

4 files changed

Lines changed: 144 additions & 0 deletions

File tree

‎docs/importer.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# SensorBucket CSV Importer Guide
2+
3+
## Overview
4+
5+
The SensorBucket CSV Importer is a powerful tool that allows you to import, update, and manage your data through simple CSV files. This guide explains how the system works and provides instructions on how to use it effectively.
6+
7+
## Supported Entity Types
8+
9+
The CSV Importer currently supports importing the following types of entities:
10+
11+
1. **Devices and Sensors** - Import devices along with their associated sensors
12+
2. **Features of Interest** - Import geographical features that sensors can be associated with
13+
14+
<figure markdown>
15+
![](../media/importer-devices.png)
16+
<figcaption>The importer screen while importing a CSV of devices and sensors</figcaption>
17+
</figure>
18+
19+
## How It Works
20+
21+
The CSV Importer follows a three-step process:
22+
23+
1. **Upload** - Upload your CSV file containing the entities you want to import
24+
2. **Reconciliation** - The system compares your CSV data with existing data in SensorBucket
25+
3. **Confirmation** - Execute the reconciliation per entity or for all entities in the import
26+
27+
This process ensures that you have full control over what gets created, updated, or deleted in your SensorBucket account.
28+
29+
## CSV File Format
30+
31+
### Devices and Sensors CSV
32+
33+
To import devices and sensors, your CSV file should include the columns below. If the device columns are left empty, but
34+
the sensor columns are filled, the sensor will be associated to the latest device row.
35+
36+
#### Device Columns
37+
- `device code` (required) - Unique identifier for the device
38+
- `device description` - Description of the device
39+
- `device properties X` - Custom properties for the device (replace X with property name)
40+
41+
#### Sensor Columns
42+
- `sensor code` (required) - Unique identifier for the sensor
43+
- `sensor description` - Description of the sensor
44+
- `sensor external_id` - External identifier for the sensor
45+
- `sensor properties X` - Custom properties for the sensor (replace X with property name)
46+
47+
#### Feature of Interest Association
48+
- `sensor feature_of_interest id` - ID of the feature of interest to associate with the sensor
49+
- `sensor feature_of_interest name` - Name of the feature of interest to associate with the sensor
50+
- `sensor feature_of_interest properties X` - Custom properties for the feature of interest
51+
52+
#### Special Columns
53+
- `DELETE` - Add this column and put "DELETE" in the row to mark a device or sensor for deletion
54+
55+
#### Example Devices and Sensors CSV
56+
57+
The sensors below can have a custom attribute named "ultrasonic_correction".
58+
59+
| device code | device description | device latitude | device longitude | device altitude | device properties dev_eui | sensor code | sensor brand | sensor description | sensor external_id | sensor feature_of_interest name | sensor properties ultrasonic_correction |
60+
| ----------- | ------------------------------------------------------- | --------------- | ---------------- | --------------- | ------------------------- | ----------- | ---------------- | -------------------------- | ------------------ | ------------------------------- | --------------------------------------- |
61+
| MFM404B | brug over Havenkanaal, Goes | 51.123123 | 3.123123 | | D49C10000000404B | JSN-SR04T | JSN | Ultrasonic distance sensor | jsnsr04t | MPN1115 | yes |
62+
| | | | | | | DS18B20 | Maxim Integrated | Temperature sensor | ds18b20 | | |
63+
| | | | | | | Antenna | Lynx WRT | Antenna | antenna | | |
64+
| MFM4053 | brug over Havenkanaal, Dorp | 51.123123 | 3.123123 | | D49C100000004053 | JSN-SR04T | JSN | Ultrasonic distance sensor | jsnsr04t | MPN1432 | yes |
65+
| | | | | | | DS18B20 | Maxim Integrated | Temperature sensor | ds18b20 | | |
66+
| | | | | | | Antenna | Lynx WRT | Antenna | antenna | | |
67+
68+
### Features of Interest CSV
69+
70+
To import features of interest, your CSV file should include the following columns:
71+
72+
#### Required Columns
73+
- `name` (required) - Name of the feature of interest
74+
75+
#### Optional Columns
76+
- `description` - Description of the feature of interest
77+
- `properties X` - Custom properties (replace X with property name)
78+
- `latitude` - Latitude coordinate for the feature
79+
- `longitude` - Longitude coordinate for the feature
80+
81+
#### Special Columns
82+
- `DELETE` - Add this column and put "DELETE" in the row to mark a feature for deletion
83+
84+
#### Example Features of Interest CSV
85+
| Name | Description | Latitude | Longitude |
86+
| ------- | ------------------------------------------------------- | --------- | --------- |
87+
| MPN1115 | brug over Havenkanaal, nabij Van der Goeskade 8, Goes | 51.123123 | 3.123123 |
88+
| MPN1432 | brug over Havenkanaal, nabij Brugstraat, Wilhelminadorp | 51.123123 | 3.123123 |
89+
90+
91+
## Import Workflow
92+
93+
### Importing Devices and Sensors
94+
95+
1. Navigate to the Importer page in the SensorBucket web interface
96+
2. Click on "Devices & Sensors"
97+
3. Upload your CSV file
98+
4. The system will analyze your file and compare it with existing data
99+
5. Review the proposed changes:
100+
- New devices/sensors will be marked for creation
101+
- Existing devices/sensors will be marked for update
102+
- Devices/sensors marked with "DELETE" will be scheduled for deletion
103+
6. (Optional) right click a device and select "reconcile this device only" to update a single device.
104+
7. (Optional) click "Reconcile all" to process the entire imported list.
105+
106+
### Importing Features of Interest
107+
108+
1. Navigate to the Importer page in the SensorBucket web interface
109+
2. Click on "Features-of-Interest"
110+
3. Upload your CSV file
111+
4. The system will analyze your file and compare it with existing data
112+
5. Review the proposed changes
113+
6. (Optional) right click a device and select "reconcile this feature-of-interest only" to update a single device.
114+
7. (Optional) click "Reconcile all" to process the entire imported list.
115+
116+
## Tips and Best Practices
117+
118+
1. **Header Detection** - The system automatically detects the header row in your CSV file, but it's best to include it as the first row
119+
2. **Incremental Updates** - You can update just a subset of your devices/sensors by including only those in your CSV
120+
3. **Validation** - The system validates your data before import and will show errors if there are issues
121+
5. **Maintain a single CSV as source** - By maintaining a single CSV per "group" of devices or locations, you will always have a source of truth
122+
123+
## Troubleshooting
124+
125+
### Common Issues
126+
127+
1. **CSV Parse Error** - Ensure your CSV is properly formatted and uses UTF-8 encoding with comma separated values
128+
2. **Missing Required Fields** - Check that all required fields (device code, sensor code, or feature name) are included
129+
3. **Duplicate Codes** - Ensure that device and sensor codes are unique within your CSV
130+
4. **Invalid Coordinates** - For features of interest, ensure latitude and longitude are valid numbers
131+
132+
### Error Messages
133+
134+
- "Could not parse CSV file, is it for devices?" - The CSV format doesn't match the expected format for devices
135+
- "Could not parse CSV file, is it for Features of Interest?" - The CSV format doesn't match the expected format for features
136+
- "Feature of interest must have a name" - The name field is missing for a feature of interest
137+
- "Cannot delete device because Device was not found" - Attempting to delete a device that doesn't exist
138+
139+
## Conclusion
140+
141+
The SensorBucket CSV Importer provides a flexible and powerful way to manage your devices, sensors, and features of interest. By following this guide, you can efficiently import and update your data using simple CSV files.
142+
143+
For additional help or to report issues, please contact the SensorBucket support team.

‎docs/media/importer-devices.png‎

103 KB
Loading

‎docs/media/importer-foi.png‎

49.1 KB
Loading

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ nav:
4646
- Overview: index.md
4747
- Introduction: introduction.md
4848
- Supporting new devices: creating-workers.md
49+
- Importing resources from a CSV: importer.md
4950
- Development:
5051
- Architecture: development/architecture.md
5152
- Data Model: development/data-model.md

0 commit comments

Comments
 (0)