# Migration Guide V1.2.0

## Changes to the Python module structure
With the growing number of classes and methods added to ifm3dpy, putting everything into the main module was beginning to get confusing and might be overwhelming to new users, therefore the Python module was split up into submodules akin to the C++ structure.  
The existing classes have been moved according to the following table:

| Old Location         | New Location                      |
| -------------------- | --------------------------------- | 
| `ifm3dpy.SemVer`       | `ifm3dpy.device.SemVer`             |
| `ifm3dpy.Device`       | `ifm3dpy.device.Device`             |
| `ifm3dpy.LegacyDevice` | `ifm3dpy.device.LegacyDevice`       |
| `ifm3dpy.O3R`          | `ifm3dpy.device.O3R`                |
| `ifm3dpy.FrameGrabber` | `ifm3dpy.framegrabber.FrameGrabber` |
| `ifm3dpy.Frame`        | `ifm3dpy.framegrabber.Frame`        |
| `ifm3dpy.buffer_id`    | `ifm3dpy.framegrabber.buffer_id`    |
| `ifm3dpy.SWUpdater`    | `ifm3dpy.swupdater.SWUpdater`       |

The old locations are now deprecated and will be fully removed in the future.  
Users should update their code to use the new locations.  
A future version of ifm3dpy will remove the deprecated locations.  

## Naming changes to `SWUpdater` Python bindings
For our Python bindings we generally use `snake_case` for method names, however the bindings for the `SWUpdater` used `PascalCase`. To align the `SWUpdater` with the rest of ifm3dpy the methods have been renamed to be `snake_case` too. 
User will need to update their code accordingly, please see the following table for a list of changed names.
| Old Name | New Name |
| ------------------ | -------------------- |
| `RebootToRecovery`   | `reboot_to_recovery`   |
| `WaitForRecovery`    | `wait_for_recovery`    |
| `RebootToProductive` | `reboot_to_productive` |
| `WaitForProductive`  | `wait_for_productive`  |
| `FlashFirmware`      | `flash_firmware`       |

## Changes to `ifm3d::json`
Note: The following only applies to the C++ interface, for Python no changes are needed.

We have been delivering a copy of [`nlohmann::json`](https://github.com/nlohmann/json) with ifm3d as part of the `device` module, this allowed users to easily and conveniently access the JSON formatted data without having to worry about parsing the output manually. 

However this approach lead to problems when users already were using `nlohmann::json` in their codebases and tried to integrate ifm3d.

To solve this problem we completely moved the implementation to the ifm3d namespace so our version doesn't interfere with any user supplied JSON library. 

Migration should be fairly easy, just fully qualify the namespace, e.g.:
```C++
json j = o3r->Get();
```
becomes:
```C++
ifm3d::json j = o3r->Get();
```

Additionally to use the user-defined string literals `operator""_json` and `operator""_json_pointer` they have to be imported from the namespace

```C++
using namespace ifm3d::literals;
ifm3d::json j = "[1,2,3]"_json;
```

Note: By default `nlohmann::json` currently places it's `operator""_json` and `operator""_json_pointer` into the global namespace, so this would lead to ambiguity errors, to solve this nlohmann can be configured to place them into the nlohmann namespace by defining `#define JSON_USE_GLOBAL_UDLS 0` before including it (see the [`nlohmann::json` doc](https://json.nlohmann.me/api/macros/json_use_global_udls/) for more details).


For details on using `ifm3d::json` and `nlohmann::json` together please take a look at the [C++ documentation for `ifm3d::json`](relurl:../../cpp_api/classifm3d_1_1json.html).