> For the complete documentation index, see [llms.txt](https://docs.ceruleansonar.com/c/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ceruleansonar.com/c/omniscan3d/getting-started/quick-start-upgrade-kit.md).

# Quick Start \[Upgrade Kit]

Use this guide if your unit is the Omniscan 3D Upgrade Kit, also referred to as the Modular system, which looks like this: 

<figure><img src="/files/IVi2xN461GGV53ABtJap" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
If your unit does not look like the one pictured above, you likely need to reference the documentation for the [Omniscan 3D AIO](/c/omniscan3d/getting-started/quick-start-aio.md) variant.&#x20;
{% endhint %}

{% hint style="info" %}
Note: As this documentation pertains to the Omniscan 3D upgrade kit, it is assumed that you already have a functioning Omniscan 450 unit. &#x20;
{% endhint %}

### Hardware Setup

Connect the following devices to power (DC 12-30V) and an Ethernet connection so that they are all reachable locally:<br>

* AX Module (Also called the RX-16) (The multibeam receive array)&#x20;

  <figure><img src="/files/ek8vnSoCWjHe4Z9XIe7x" alt="" width="375"><figcaption></figcaption></figure>
* BX Module (The Omniscan 450 FS, SS, or Compact)
* The device that will run the SonarView docker container (Linux laptop / desktop, or a SBC such as the Raspberry Pi).&#x20;

{% hint style="info" %}
For port and starboard OS3D kits, we recommend completing this setup procedure with only the starboard unit connected first. Once that unit is set up and working properly, repeat the software steps with both units connected.
{% endhint %}

## Software Setup

#### **1. Install SonarView**

The OmniScan 3D currently requires the Docker version of SonarView. On vehicles running BlueOS, the SonarView BlueOS extension uses the Docker version, so it is also compatible.

{% hint style="danger" %}
SonarView 1.14.40 or later is required. 1.14.68 is recommended at this time.&#x20;
{% endhint %}

{% tabs %}
{% tab title="BlueOS Extension" %}
To install the SonarView BlueOS extension, follow the instructions found [here](/c/sonarview/installation/blueos.md)

{% hint style="danger" %}
We \*highly\* recommend using BlueOS 1.4.4-beta.1 or later. If you cannot upgrade your BlueOS version, you must disable the ping service every boot and restart the SonarView extension as described below. You can skip the next step if using a recommended BlueOS version
{% endhint %}

**Disabling Ping Service for BlueOS**&#x20;

1. Open the BlueOS Terminal in a web browser.&#x20;
2. Press CTRL+B, then S.&#x20;
3. Use Arrow keys to navigate to the Ping service&#x20;
4. Use CTRL+C to kill the process.&#x20;
5. Leave this terminal open in a tab. In a separate browser tab, go to the BlueOS Installed Extensions page and restart the SonarView container. You can watch the Container logs right after it starts to see if it successfully binds to port 30303.&#x20;
6. If all is well and your devices are recognized, you should see output similar to this:

```
TCP Listener on port 62312...
HTTP server started on port 7078, serving from: ./web
successful udp bind on 192.168.2.2:50505
successful udp bind on 0.0.0.0:30303
InterfaceManager::init() completed at IP address 192.168.2.2
awaitActivity timeout
ABxDiscoveryHandler: broadcasting discovery msg: 'OS3D-DISCOVERY-1;PI_IP: 192.168.2.2 ,SPOOF: 192.168.2.253 '
ABxDiscoveryHandler received reply: '{ "message_type": "ABxDiscoveryResponse", "device_type": "BX", "MAC": "00:80:e1:4e:1c:24"}'
ABxDiscoveryHandler received reply: '{ "message_type": "ABxDiscoveryResponse", "device_type": "AX", "MAC": "00:80:e1:29:7f:26"}'
awaitActivity timeout
```

Now you can use SonarView in a separate browser tab (leave the terminal from step #5 open). This process will need to be repeated on each boot until this issue is resolved via BlueOS Update.&#x20;
{% endtab %}

{% tab title="Docker Version" %}
The docker container can run on any Linux host. To install the Docker version without BlueOS, follow instructions found [here](/c/sonarview/installation/docker.md)
{% endtab %}
{% endtabs %}

#### 2. Discover Devices

Open SonarView and go into Device Discovery. If your devices are powered on and reachable, you'll see the Omniscan 3D in the Discovered Devices list

<figure><img src="/files/jV5XQ59ErLKeTt87b766" alt=""><figcaption></figcaption></figure>

#### 3. Open the OS3D Configuration Dialog

Once connected, navigate to the left side bar and open the **OS3D Configuration**. If not visible here, check under the **Advanced** tab

<figure><img src="/files/KtBBlYpjS4c5rsikviQY" alt=""><figcaption></figcaption></figure>

#### 4. Configure the OS3D

You should see something like this:

<figure><img src="/files/LrQd1bT72OBPW67LkSjy" alt=""><figcaption></figcaption></figure>

1. If you have a regular Omniscan unit, you will need to update the firmware to be compatable with the Omniscan3D. Find those instructions [here](/c/omniscan3d/getting-started/omniscan-less-than-greater-than-omniscan3d.md)
2. Assuming only one AX (RX16) and one BX (Omniscan) are connected, the `ax_mac` and `bx_mac` fields should populate automatically. If they do not, or if the values do not match the devices listed under **Discovered Devices** above, copy those values into the appropriate fields. Be sure to keep the quotation marks.
3. Configure `mount_fsd` (forward, starboard, down) so it matches the unit’s position and yaw angle relative to your position and heading source.
4. Set the `spoof_ip` value to a valid IP address within the range used by the machine running SonarView. On a factory BlueOS installation, any address in the `192.168.2.xxx` range should work, provided it does not conflict with another device—for example, do not use `192.168.2.2`. You can also run `ifconfig` in a terminal to check for a valid address.
5. Click **Apply Changes** to confirm changes. This should restart the device.
6. If you have a second unit, connect it to the system while keeping the first one connected and configure the ax\_mac, bx\_mac, and mount\_fsd as a second device in that array as shown below

```
{
  "devices": [
    {
      "ax_mac": "00:80:e1:4d:7c:24",
      "bx_mac": "00:80:e1:27:02:24",
      "mount_fsd": {
        "x_mm": 0,
        "y_mm": 0,
        "yaw_deg": 90,
        "z_mm": 0
      },
      "name": "Omniscan 3D Starboard"
    },
    {
      "ax_mac": "00:80:e1:4d:7c:23",
      "bx_mac": "00:80:e1:27:ab:24",
      "mount_fsd": {
        "x_mm": 0,
        "y_mm": 0,
        "yaw_deg": -90,
        "z_mm": 0
      },
      "name": "Omniscan 3D Port"
    }
  ],
  "spoof_ip": "192.168.2.200",
  "type": "os3d_config"
}
```

With everything connected and configured, you should now be able to connect and start collecting data. Follow the links below for next steps

<table data-view="cards"><thead><tr><th></th><th data-type="content-ref"></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td>Configure Source of Position and Heading</td><td><a href="/pages/QTLvwV0rDGTX0Ya2WGqG">/pages/QTLvwV0rDGTX0Ya2WGqG</a></td><td><a href="/files/oeCDizySsm8V9Fbe4frT">/files/oeCDizySsm8V9Fbe4frT</a></td></tr><tr><td>Change Firmware on Omnsican Unit</td><td><a href="/pages/uA5MvtcDh4NvYCGwm1Yh">/pages/uA5MvtcDh4NvYCGwm1Yh</a></td><td><a href="/files/IrS1SGTpbjBpeTgx7sVl">/files/IrS1SGTpbjBpeTgx7sVl</a></td></tr><tr><td>Using SonarView for the Omniscan 3D</td><td><a href="/pages/ZnKXhqRR8fhH4AUBkBqS">/pages/ZnKXhqRR8fhH4AUBkBqS</a></td><td><a href="/files/d41RjQUQgwjEo3irtYUw">/files/d41RjQUQgwjEo3irtYUw</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ceruleansonar.com/c/omniscan3d/getting-started/quick-start-upgrade-kit.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.