DOCSEARCHbyAlgolia
Submit Docs

AgOpenGPS Documentation

repository·develop·Indexed 21 days ago

https://github.com/agopengps-official/agopengps

Precision agricultural software for guidance, mapping, and section control. The system processes GPS/IMU data via AgIO to calculate steering angles using Stanley or Pure Pursuit algorithms and manages implement application to prevent over-application. Key features include AB line, AB Curve, and Contour guidance, Auto Headland 'UTurn' functionality, and support for up to 64 sections of section control.

Tokens
16.5K
Snippets
30
Records
66
Agent score
76%

What's inside AgOpenGPS

  1. Understand the AgOpenGPS System Architecture

    develop

    AgOpenGPS is a guidance system that processes GPS/IMU data to calculate guidance and output steering commands. The high-level data flow is:

    1. Hardware Input: GPS/IMU data is received by AgIO.
    2. Communication: AgIO sends data via UDP (loopback 127.x.x.x) to AgOpenGPS.
    3. Processing: AgOpenGPS calculates guidance logic.
    4. Output: Steering commands are sent to the steering module via CAN/Serial/UDP to drive the AutoSteer hardware.

    Project Structure

    • GPS/: The main application containing core logic and state management.
    • AgOpenGPS.Core/: A shared library containing Geo models, conversions, helpers, file I/O, and ViewModels.
    • AgIO/: The I/O handler responsible for NTRIP, GPS, IMU, and UDP communication.
    • GPS_Out/: Handles NMEA serial output.
    • AgDiag/: Diagnostic tools.
    • ModSim/: Module simulator.
    • Keypad/: Hardware keypad support.

  2. Overview of the AgOpenGPS Settings System

    develop

    AgOpenGPS uses a split settings system to organize configuration into three distinct categories. This separation improves organization and allows for different storage profiles (e.g., different vehicles or tools).

    Settings TypeFile PathPurpose
    VehicleGPS/Properties/VehicleSettings.csSteer settings, IMU, GPS config, brand presets
    ToolGPS/Properties/ToolSettings.csSections, tramlines, relays, Arduino machines
    EnvironmentGPS/Properties/Settings.csDisplay, sounds, window positions, colors

    Storage Mechanism: All settings are stored in the Windows Registry rather than .config files.

  3. Understand AgOpenGPS naming conventions

    develop

    The project follows a strict naming convention to distinguish between different types of code entities:

    • GPS Classes: Prefixed with C (e.g., CSection, CVehicle, CTool). These represent core logic and data structures within the GPS module.
    • Forms: Prefixed with Form (e.g., FormGPS). These represent UI components.
    • Core Models: No prefix (e.g., GeoCoord, Wgs84, Field). These are shared data models used across the application.

  4. Understand the AgOpenGPS business logic distribution

    develop

    The application's business logic is distributed across two primary locations:

    1. GPS/Classes/: Contains the main application logic, including state management and guidance algorithms.
    2. AgOpenGPS.Core/Models/: Contains reusable models, geographic conversions, and helper utilities.

  5. Understand the AgOpenGPS PGN Protocol Structure

    develop

    AgOpenGPS uses a custom PGN (Parameter Group Number) protocol over UDP for communication between AgIO and the main application. The protocol wraps data in a specific byte structure including headers, a PGN identifier, length, payload, and a CRC checksum.

    Byte Structure:

    • 0x80: Standard AOG header
    • 0x81: PGN header
    • 0x7F: Source address
    • [Varies]: PGN identifier
    • [Varies]: Data length
    • [Varies]: Data payload
    • [N]: CRC checksum (sum of bytes from index 2 to N-1)
    [0x80, 0x81, 0x7F, PGN, Length, Data..., CRC]

  6. Understand the AgOpenGPS software architecture

    develop

    AgOpenGPS consists of two primary programs that work together:

    • AgIO: Acts as the communication hub for external hardware/data.
    • AgOpenGPS: The main application.

    You can run either program independently, and they can be run within each other. You only need to run the AgOpenGPS application if you are using the simulator.

    Core Capabilities:

    • Positioning: Reads NMEA strings for recording and mapping agricultural position information.
    • Section Control: Supports up to 16 sections with unique widths, or up to 64 sections of the same width, to prevent product over-application.
    • Guidance: Outputs Pure pursuit steer angles for AB line, AB Curve, and Contour guidance.
    • Auto Headland: Includes 'UTurn' functionality for Curve and AB Line with loops for narrow equipment.
    • Mapping: Supports background mapping.

  7. Access main application state via FormGPS reference

    develop

    Most core classes maintain a reference to the main application form (FormGPS), typically stored in a private field mf. You can use this reference to access the primary running instances of the system's core components:

    • mf.vehicle: The current CVehicle instance.
    • mf.tool: The current CTool instance.
    • mf.ahrs: The current CAHRS instance.
    • mf.trk: The current CTrack instance.
    • mf.pn: Position and Navigation data.
    // Accessing core components through the FormGPS reference
var wheelbase = mf.vehicle.wheelbase;
var toolWidth = mf.tool.toolWidth;
var currentPos = mf.pn;

  8. Use Easy Drive Mode for quick GPS guidance

    develop

    Easy Drive Mode is a quick-start mode designed for driving with GPS guidance without the need to load a specific field from disk. This mode is ideal for temporary guidance sessions where you want to set a working width and pivot distance to create AB lines or Curves without permanent file creation.

    Key Characteristics:

    • In-Memory Only: Everything created (lines, curves, tracks) stays in memory. Nothing is saved to disk, and no field directory is created.
    • Simplified Tooling: It configures a single-section Rigid Tool automatically based on your inputs.
    • Limited Features: To maintain simplicity and prevent accidental data corruption, several features are disabled, including Config screens, Vehicle/Tool profile loading, and Headland, Boundary, or Tram tools.
    • Temporary Status: The field label will display "Easy Drive" or "Temporary" during an active session.

  9. Understand Steering Algorithms (Stanley vs Pure Pursuit)

    develop

    AgOpenGPS uses two primary algorithms for calculating steering angles. The choice is controlled by the setVehicle_isStanleyUsed setting.

    Stanley Algorithm

    Enabled when: setVehicle_isStanleyUsed = true Formula: steerAngle = atan((distanceError * gain) / speed) + headingError * gain Key Gains:

    • stanleyDistanceErrorGain: Distance error multiplier
    • stanleyHeadingErrorGain: Heading error multiplier
    • stanleyIntegralGainAB: Integral gain for AB lines Implementation: Classes/CGuidance.cs -> DoSteerAngleCalc()

    Pure Pursuit Algorithm

    Enabled when: setVehicle_isStanleyUsed = false Formula: steerAngle = atan2(2 * wheelbase * sin(error), lookahead) Key Gains:

    • purePursuitIntegralGainAB: Integral gain for AB lines
    • goalPointLookAheadHold: Lookahead when holding
    • goalPointLookAheadMult: Lookahead multiplier Implementation: Classes/CTrackMethods.cs -> GoalPoint()

  10. Configure UDP Network settings for AgOpenGPS

    develop

    For local communication (loopback), use the following network parameters:

    ParameterValue
    AOG Listen Port15555
    AgIO Endpoint127.255.255.255:17777
    ProtocolUDP
    Subnet127.x.x.x

    Connection Setup Example:

    // AOG binds to loopback port 15555
loopBackSocket.Bind(new IPEndPoint(IPAddress.Loopback, 15555));

// Send to AgIO on 127.255.255.255:17777
EndPoint epAgIO = new IPEndPoint(IPAddress.Parse("127.255.255.255"), 17777);

  11. Build AgOpenGPS from source

    develop

    To build the project from the source code:

    1. Clone the repository using a tool like Visual Studio.
    2. Open the solution file located at SourceCode/AgOpenGPS.sln in Visual Studio.
    3. Apply your changes and (re)build the solution.
    4. To generate a single folder containing all applications, run the following command from the root folder of the repository:
    dotnet publish SourceCode/AgOpenGPS.sln

  12. Implement PGN sending and receiving logic

    develop

    To integrate with the PGN protocol, you must implement logic to calculate/verify the CRC and handle the UDP socket.

    Sending: Calculate the CRC by summing bytes from index 2 to length - 2, then assign the result to the last byte. Use BeginSendTo for asynchronous transmission.

    Receiving: Validate the header (0x80, 0x81), calculate the expected CRC from the payload, and compare it against the received CRC byte at the end of the packet. If valid, switch on the PGN identifier (byte at index 3) to process the specific message type.

    // Sending PGN to AgIO
public void SendPgnToLoop(byte[] byteData)
{
    if (loopBackSocket != null && byteData.Length > 2)
    {
        // Calculate CRC
        int crc = 0;
        for (int i = 2; i + 1 < byteData.Length; i++)
        {
            crc += byteData[i];
        }
        byteData[byteData.Length - 1] = (byte)crc;

        // Send to endpoint
        loopBackSocket.BeginSendTo(byteData, 0, byteData.Length, 
            SocketFlags.None, epAgIO, SendAsyncLoopData, null);
    }
}

// Receiving PGN from AgIO
private void ReceiveFromAgIO(byte[] data)
{
    // Validate header
    if (data.Length > 4 && data[0] == 0x80 && data[1] == 0x81)
    {
        // Validate CRC
        int Length = Math.Max((data[4]) + 5, 5);
        byte CK_A = 0;
        for (int j = 2; j < Length; j++)
        {
            CK_A += data[j];
        }

        if (data[Length] != (byte)CK_A)
        {
            return; // CRC mismatch
        }

        // Process by PGN
        switch (data[3])
        {
            case 0xD6: // GPS Position
                // Process...
                break;
            // ... other PGNs
        }
    }
}